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Flask 扩展 文档 汇总 


来 源 : Python 中 文学 习 大 本 营 


Flask-Babel 


Flask-Babel 是 一 个 Flask 的 扩展 ， 在 babel, pytz 和 speaklater 的 帮助 下 添加 i18n 和 110n 5 
持 到 任何 Flask 应 用 。 它 内 置 了 一 个 时 间 格 式 化 的 支持 ， 同 样 内 置 了 一 个 非常 简单 和 友好 的 
gettext 翻译 的 接口 。 


mo yt 
安装 
下 面 命令 可 以 安装 扩展 : 


$ easy install Flask-Babel 


或 者 如 果 你 安装 了 pip: 


$ pip install Flask-Babel 


请 注意 Flask-Babel 需要 Jinja 2.5。 如 果 你 安装 一 个 老 的 版 本 你 将 会 需要 升级 或 者 禁止 Jinja 
支持 。 


Acie 
在 配置 好 应 用 后 所 有 需要 做 的 就 是 实例 化 一 个 caver 对 象 : 


from flask import Flask 
from flask.ext.babel import Babel 


app = Flask( name ) 


app.config.from pyfile('mysettings.cfg') 
babel - Babel(app) 


babel 对 象 本 身 以 后 支持 用 于 配置 babel。Babel 有 两 个 配置 值 ， 这 两 个 配置 值 能 够 改变 内 部 
的 默认 值 : 


如 果 没 有 指定 地 域 且 选 择 器 已 经 注册 ， SAY ERAT. EA 
认 是 'en' 。 

用 户 默认 使 用 的 时 区 。 默 认 是 curc' 。 选 用 默 认 值 的 时 
候 ， 你 的 应 用 内 部 必须 使 用 该 时 区 。 


BABEL_DEFAULT_LOCALE 


BABEL_DEFAULT_TIMEZONE 


对 于 更 复杂 的 应 用 你 可 能 希望 对 于 不 同 的 用 户 有 多 个 应 用 ， 这 个 时 候 是 选择 器 函数 派 上 用 场 
的 时 候 。babel 扩展 第 一 次 需要 当前 用 户 的 地 区 的 时 候 ， 它 会 调用 localeselector() BR, 
第 一 次 需要 时 区 的 时 候 ， 它 会 调用 timezoneselector() WR. 


如 果 这 些 方 法 的 任何 一 个 返回 none ， 扩 展 将 会 自动 回落 到 配置 中 的 值 。 而 且 为 了 效率 考虑 
函数 只 会 调用 一 次 并 且 返 回 值 会 被 缓存 。 如 果 你 需要 在 一 个 请 求 中 切换 语言 的 话 ， 你 可 以 
refresh() 缓存 。 


选择 器 图 数 的 例子 : 


from flask import g, request 


Qbabel.localeselector 
def get locale(): 
4 if a user is logged in, use the locale from the user settings 
user - getattr(g, 'user', None) 
if user is not None: 
return user.locale 
# otherwise try to guess the language from the user accept 
4 header the browser transmits. We support de/fr/en in this 
# example. The best match wins. 
return request.accept languages.best match(['de', 'fr', 'en']) 


Qbabel.timezoneselector 
def get timezone(): 
user - getattr(g, 'user', None) 


if user is not None: 
return user.timezone 


以 上 的 例子 假设 当前 的 用 户 是 存储 在 flask.g 对 象 中 。 


格式 化 日 期 


你 可 以 使 用 format datetime() , format date() , format time() 以 及 format timedelta() 

RAKSHA Vd1ABBERS—^ datetime.datetime (MA 

datetime.date , datetime.time 以 及 datetime.timedelta ) 对 象 作为 第 一 个 参数 ， 其 它 参 

a 的 格式 化 字符 串 。 应 用 程序 应 该 使 用 天 然 的 datetime 对 象 且 内 部 使 用 UTC 作 
为 默认 时 区 。 格 式 化 的 时 候 会 自动 地 转换 成 用 户 时 区 以 防 它 不 同 于 UTC。 


为 了 能 够 在 命令 行 中 使 用 日 期 格式 化 ， 你 可 以 使 用 test request context() 方法 : 


>>> app.test request context().push() 


这 里 是 一 些 例子 : 


>>> from flask.ext.babel import format datetime 

>>> from datetime import datetime 

>>> format datetime(datetime(1987, 3, 5, 17, 12)) 

u'Mar 5, 1987 5:12:00 PM' 

>>> format datetime(datetime(1987, 3, 5, 17, 12), 'full') 
u'Thursday, March 5, 1987 5:12:00 PM World (GMT) Time' 

>>> format datetime(datetime(1987, 3, 5, 17, 12), 'short') 
u'3/5/87 5:12 PM' 

>>> format datetime(datetime(1987, 3, 5, 17, 12), 'dd mm yyy') 
u'05 12 1987' 

>>> format datetime(datetime(1987, 3, 5, 17, 12), 'dd mm yyyy') 
u'05 12 1987' 


接着 用 不 同 的 语言 再 次 格式 化 : 


>>> app.config['BABEL DEFAULT LOCALE'] = 'de' 

>>> from flask.ext.babel import refresh; refresh() 

>>> format datetime(datetime(1987, 3, 5, 17, 12), 'EEEE, d. MMMM yyyy H:mm') 
u'Donnerstag, 5N. MNxe4rz 1987 17:12' 


关于 格式 例子 的 更 多 信息 请 参阅 babel 文档 。 


使 用 翻译 


日 期 格式 化 之 外 的 另 一 个 部 分 就 是 翻译 。Flask 使 用 gettext 和 Babel 配合 一 起 实现 翻译 的 
功能 。gettext 的 作用 就 是 你 可 以 标记 某 些 字符 串 作 为 翻译 的 内 容 并 且 一 个 工具 会 从 应 用 中 挑 
选 这 些 ， 接 着 把 它们 放 和 一 个 单独 的 文件 为 你 来 翻译 。 在 运行 的 时 候 原始 的 字符 串 (应 该 是 
Ris) 将 会 被 你 选择 的 语言 蔡 换 掉 。 


有 两 个 函数 可 以 用 来 完成 翻译 : gettext() 和 ngettext() 。 第 一 个 画 数 用 于 翻译 含有 0 个 
或 者 1 个 字符 串 参 数 的 字符 串 ， 第 二 个 参数 用 于 翻译 含有 多 个 字符 串 参 数 的 字符 串 。 这 里 有 
些 示 例 : 


from flask.ext.babel import gettext, ngettext 


gettext(u'A simple string!) 
gettext(u'Value: %(value)s', value=42) 
ngettext(u'%(num)s Apple', u'%(num)s Apples', number_of_apples) 


e es Wada 量 字符 串 并 且 在 请 求 之 外 定义 它们 的 话 ， Ce 
个 “懒惰 "字符 串 。 "懒惰 ?字符 串 直 到 它们 实际 被 使 用 的 时 候 才 会 计算 。 为 了 使 用 一 个 “懒惰 " 字 
符 串 ， 请 使 用 lazy_gettext() WAL: 











from flask.ext.babel import lazy gettext 


class MyForm(formlibrary.FormBase): 
Success message - lazy gettext(u'The form was successfully saved.') 


Flask-Babel 如 何 找到 翻译 ? 首先 你 必须 要 生成 翻译 。 这 里 是 你 如 何 做 到 这 一 点 : 


翻译 应 用 


首先 你 需要 用 gettext() 或 者 ngettext() 在 你 的 应 用 中 标记 你 要 翻译 的 所 有 字符 串 。 在 这 
之 后 ， 是 时 候 创 建 一 个 .pot 文件 。 一 个 .pot 文件 包含 所 有 的 字符 串 ， 并 且 它 是 一 个 
.po 文件 的 模板 ， .po 文件 包含 已 经 翻译 的 字符 串 。Babel 可 以 为 你 做 所 有 的 这 一 切 。 


首先 你 必须 进入 到 你 的 应 用 所 在 的 文件 夹 中 并 且 创 建 一 个 映射 文件 夹 。 对 于 典型 的 Flask 应 
用 ， 这 是 你 要 的 : 


[python: **.py] 
[jinja2: **/templates/**.html] 
extensions-jinja2.ext.autoescape,jinja2.ext.with 


在 你 的 应 用 中 把 它 保存 成 babel.ctg 或 者 其 它 类 似 的 东 东 。 接 着 是 时 候 运 行 来 自 Babel 中 的 
pybabel 命令 来 提取 你 的 字符 串 : 


$ pybabel extract -F babel.cfg -o messages.pot . 


如 果 你 使 用 了 1azy_gettext() WA, M&E pybabel， 这 时 候 需 要 这 样 运行 pybabel : 


$ pybabel extract -F babel.cfg -k lazy gettext -o messages.pot . 


这 会 使 用 babel.cfg 文件 中 的 映射 并 且 在 messages.pot 里 存储 生成 的 模板 。 现在 可 以 创建 
第 一 个 翻译 。 例 如 使 用 这 个 命令 可 以 翻译 成 德语 : 


$ pybabel init -i messages.pot -d translations -1 de 


-d translations 告诉 pybabel 存储 翻译 在 这 个 文件 夹 中 。 这 是 Flask-Babel 寻找 翻译 的 地 
方 。 可 以 把 它 放 在 你 的 模板 文件 夹 旁边 。 


现在 如 有 必要 编辑 translations/de/LC_MESSAGES/messages.po 文件 。 如 果 你 感到 困惑 的 话 请 
参阅 一 些 gettext 教程 。 


为 了 能 用 需要 编译 翻译 ， pybabel 再 次 大 显 神 通 : 


$ pybabel compile -d translations 


如 果 字 符 捉 变化 了 怎么 办 ? 像 上 面 一 样 创建 一 个 新 的 messages.pot 接着 让 pybabel 整合 这 
些 变化 : 


$ pybabel update -i messages.pot -d translations 


之 后 有 些 字符 串 可 能 会 被 标记 成 含糊 不 清 。 如 果 有 含糊 不 清 的 字符 串 的 时 候 ， 务 必 在 编译 之 
前 手动 地 检查 他 们 并 且 移 除 含糊 不 清 的 标志 。 


问题 
在 Snow Leopard 上 pybabel 最 有 可 能 会 以 一 个 异常 而 失败 。 如 果 发 生 了 ， 检 查 命 令 的 输出 


是 否 是 UTF-8: 


$ echo $LC_CTYPE 
UTF-8 


不 幸 地 这 是 一 个 OS X 问题 。 为 了 修复 它 ， 请 把 如 下 的 行 加 入 到 你 的 ~/.profile 文件 : 


export LC_CTYPE=en_US.utf-8 


接着 重启 你 的 终端 。 


API 


文档 这 一 部 分 列 出 了 Flask-Babel 中 每 一 个 公开 的 类 或 者 函数 。 


Ac ie 


class flask.ext.babel.Babel(app=None, default_locale='en', default_timezone='UTC', date_fo 


Central controller class that can be used to configure how Flask-Babel behaves. Each 
application that wants to use Flask-Babel has to create, or run init app() on, an instance 
of this class after the configuration was initialized. 


default locale 
The default locale from the configuration as instance of a babel.Locale object. 
default timezone 
The default timezone from the configuration as instance of a pytz.timezone object. 
init app(app) 

Set up this instance for use with app, if no app was passed to the constructor. 

list translations() 


Returns a list of all the locales translations exist for. The list returned will be filled with actual 
locale objects and not just strings. 


New in version 0.6. 


localeselector(f) 


Registers a callback function for locale selection. The default behaves as if a function was 
registered that returns wone all the time. If None is returned, the locale falls back to the one 
from the configuration. 


This has to return the locale as string (eg: 'de AT' , " en us °) 


timezoneselector(f) 


Registers a callback function for timezone selection. The default behaves as if a function 
was registered that returns None all the time. If None is returned, the timezone falls back to 
the one from the configuration. 


This has to return the timezone as string (eg: 'Europe/vienna' ) 


Context 函数 


flask.ext.babel.get translations() 


Returns the correct gettext translations that should be used for this request. This will never 
fail and return a dummy translation object if used outside of the request or if a translation 
cannot be found. 


flask.ext.babel.get locale() 


Returns the locale that should be used for this request as babel.Locale object. This returns 
None if used outside of a request. 


flask.ext.babel.get timezone() 


Returns the timezone that should be used for this request as pytz.timezone object. This 
returns None if used outside of a request. 


Datetime 2X 
flask.ext.babel.to user timezone(datetime) 


Convert a datetime object to the user's timezone. This automatically happens on all date 
formatting unless rebasing is disabled. If you need to convert a datetime.datetime object at 
any time to the user's timezone (as returned by get timezone() this function can be used). 


flask.ext.babel.to utc(datetime) 
Convert a datetime object to UTC and drop tzinfo. This is the opposite operation to 
to user timezone() 


flask.ext.babel.format datetime(datetime-None, format=None, rebase-True) 


Return a date formatted according to the given pattern. If no datetime objectis passed, the 
current time is assumed. By default rebasing happens which causes the object to be 
converted to the users's timezone (as returned by to user timezone() ). This function 
formats both date and time. 


The format parameter can either be 'short' , 'medium' , 'long' Or 'full' (in which 
cause the language's default for that setting is used, or the default from the 
Babel.date formats mapping is used) or a format string as documented by Babel. 
This function is also available in the template context as filter named datetimeformat . 
flask.ext.babel.format date(datezNone, format=None, rebase=True) 
Return a date formatted according to the given pattern. If no datetime or date objectis 
passed, the current time is assumed. By default rebasing happens which causes the object 


to be converted to the users's timezone (as returned by to user timezone() ). This function 
only formats the date part of a datetime object. 


The format parameter can either be 'short' , 'medium' , 'long' Or 'full' (in which 
cause the language's default for that setting is used, or the default from the 
Babel.date formats mapping is used) or a format string as documented by Babel. 


This function is also available in the template context as filter named dateformat . 
flask.ext.babel.format_time(time=None, format=None, rebase=True) 


Return a time formatted according to the given pattern. If no datetime object is passed, the 
current time is assumed. By default rebasing happens which causes the object to be 
converted to the users’s timezone (as returned by to_user_timezone() ). This function 
formats both date and time. 


The format parameter can either be 'short' , 'medium' , 'long' Or 'full' (in which 
cause the language's default for that setting is used, or the default from the 
Babel.date formats mapping is used) or a format string as documented by Babel. 


This function is also available in the template context as filter named timeformat . 


flask.ext.babel.format timedelta(datetime or timedelta, granularity-'second') 


Format the elapsed time from the given date to now or the given timedelta. This currently 
requires an unreleased development version of Babel. 


This function is also available in the template context as filter named timedeltaformat . 


Gettext ŽI 


flask.ext.babel.gettext(string, **variables) 


Translates a string with the current locale and passes in the given keyword arguments as 
mapping to a string formatting string. 


gettext(u'Hello World!') 
gettext(u'Hello %(name)s!', name='World') 


flask.ext.babel.ngettext(singular, plural, num, **variables) 


Translates a string with the current locale and passes in the given keyword arguments as 
mapping to a string formatting string. The num parameter is used to dispatch between 
singular and various plural forms of the message. It is available in the format string as 
%(num)d Or %(num)s . The source language should be English or a similar language which 
only has one plural form. 


ngettext(u'%(num)d Apple', u'%(num)d Apples', num=len(apples) ) 


flask.ext.babel.pgettext(context, string, **variables) 
Like gettext() but with a context. 


New in version 0.7. 


flask.ext.babel.npgettext(context, singular, plural, num, **variables) 
Like ngettext() but with a context. 


New in version 0.7. 


flask.ext.babel.lazy gettext(string, **variables) 


Like gettext() butthe string returned is lazy which means it will be translated when it is 
used as an actual string. 


Example: 


hello - lazy gettext(u'Hello World') 


@app.route('/') 
def index(): 
return unicode(hello) 


flask.ext.babel.lazy pgettext(context, string, **variables) 


Like pgettext() butthe string returned is lazy which means it will be translated when it is 
used as an actual string. 


New in version 0.7. 


低层 的 API 


flask.ext.babel.refresh() 


Refreshes the cached timezones and locale information. This can be used to switch a 
translation between a request and if you want the changes to take place immediately, not 
just with the next request: 


user.timezone = request.form['timezone'] 
user.locale = request.form['locale' ] 
refresh() 

flash(gettext('Language was changed')) 


Without that refresh, the flash() function would probably return English text and a now 
German page. 


Flask-Cache 
安装 


使 用 下 面 的 命令 行 安 装 Flask-Cache: 


$ easy install Flask-Cache 


或 者 可 以 用 下 面 的 命令 行 ， 如 果 安 装 了 pip: 


$ pip install Flask-Cache 


缓存 (Cache) 是 通过 使 用 一 个 cache 实例 进行 管理 : 
from flask import Flask 
from flask.ext.cache import Cache 
app = Flask( name ) 


# Check Configuring Flask-Cache section for more details 
cache = Cache(app, config={'CACHE_TYPE': 'simple'}) 


你 能 够 用 init app 方法 在 初始 化 cache 后 设置 它 : 


cache = Cache(config={'CACHE_TYPE': 'simple'}) 


app = Flask( name ) 
cache.init app(app) 


如 果 有 多 个 cache 实例 以 及 每 一 个 实例 都 有 不 同 后 端的 话 ( 换 句 话说 ， 就 是 每 一 个 实例 使 用 
不 用 的 缓存 类 型 CACHE_TYPE) ， 使 用 配置 字典 是 十 分 有 用 的 : 


#: Method A: During instantiation of class 

cache = Cache(config={'CACHE_TYPE': 'simple'}) 

#: Method B: During init_app call 
cache.init_app(app, config={'CACHE_TYPE': 'simple'}) 


New in version 0.7. 


2 TFA E] IŽ 


使 用 装饰 器 cached() 能 够 缓存 视图 男 数 。 它 在 默认 情况 下 使 用 请 求 路 径 (request.path) 作 为 
cache key: 
@cache.cached(timeout=50) 


def index(): 
return render template('index.html') 


该 装饰 器 有 一 个 可 选 的 参数 : unless ， 它 允许 一 个 可 调用 的 、 返 回 值 是 True 或 者 False 的 函 
数 。 如 果 unless 返回 True ， 将 会 完全 忽略 缓存 机 制 〈 内 置 的 缓存 机 制 会 完全 不 起 作 
用 ) o 


同样 地 ， 使 用 @cached Jesh artEa E TERSCOIEG3UUEEDERATABUILIR, M-NEBKESEBE 
key prefix ， 否 则 会 使 用 请 求 路 径 (request.path) 作 为 cache_key: 


@cache.cached(timeout=50, key prefix-'all comments') 
def get all comments(): 

comments - do serious dbio() 

return [x.author for x in comments] 


cached comments = get all comments() 


Memoization (一 种 缓存 技术 ) 


请 参看 memoize() 

在 memoization 中 ， 画 数 参数 同样 包含 cache_key。 

Note 

如 果 函 数 不 接 受 参 数 的 话 ， cached() 和 memoize() 两 者 的 作用 是 一 样 的 。 


Memoize 同 桩 也 为 类 成 员 函 数 而 设计 ， 因 为 它 根 据 identity ‘self RF ‘cls 参数 考虑 进 作为 
缓存 键 的 一 部 分 。 


memoization 背 后 的 理论 是 : 在 一 次 请 求 中 如 果 一 个 函数 需要 被 调用 多 次 ， 它 只 会 计算 第 一 次 
使 用 这 些 参 数 调 用 该 函数 。 例 如 ， 存 在 一 个 决定 用 户 角色 的 sqlalchemy 对 象 ， 在 一 个 请 求 中 
可 能 需要 多 次 调用 这 个 函数 。 为 了 避免 每 次 都 从 数据 库 获取 信息 ， 你 可 以 这 样 做 : 
class Person(db.Model): 
Qcache.memoize(50) 


def has membership(self, role id): 
return Group.query.filter by(user-self, role id-role id).count() >= 1 


Warning 


使 用 可 变 对 象 (例如 类 ) 作为 缓存 键 的 一 部 分 是 十 分 棘手 的 。 建 议 最 好 不 要 让 一 个 对 象 的 实 
例 成 为 一 个 memoized 画 数 。 然 而 ，memoize 在 义理 参数 的 时 候 会 执行 repr()， 因 此 如 果 一 个 
对 象 有 repr 函数， 并 且 返 回 一 个 唯一 标识 该 对 象 的 字符 串 ， 它 将 能 够 作为 缓存 键 的 一 部 
分 。 


例如 ， 一 个 sqlalchemy person 对 象 ， 它 返回 数据 库 的 ID 作为 唯一 标识 符 的 一 部 分 : 


class Person(db.Model): 
def repr (self): 
return "%s(%S)" % (self. class . name , self.id) 





删除 memoize 的 缓存 
New in version 0.2. 


在 每 个 函数 的 基础 上 ， 您 可 能 需要 删除 缓存 。 使 用 上 面 的 例子 ， 让 我 们 来 改变 用 户 权 限 ， 并 
将 它们 分 配 到 一 个 角色 ， 如 果 它 们 新 拥有 或 者 失去 某 些 成 员 关 系 ， 现 在 你 需要 重新 计算 。 你 
能 够 用 delete memoizea() AUE 3X PI EL BJ: 


cache.delete memoized('user has membership') 


Note 


如 果 仅 仅 只 有 图 数 名 作为 参数 ， 所 有 的 memoized 的 版 本 将 会 无 效 的 。 然 而 ， 您 可 以 删除 特定 
的 缓存 提供 缓存 时 相同 的 参数 值 。 在 下 面 的 例子 中 ， 只 有 user 角色 缓存 被 删除 : 

user has membership('demo', 'admin') 

user has membership('demo', 'user') 


cache.delete memoized('user has membership', 'demo', 'user') 


缓存 Jinja2 片 段 
用 法 : 


{% cache [timeout [,[key1, [key2, ...]]]] %} 


(96 endcache 96) 


默认 情况 下 “模版 文件 路 径 ”»+" 片 段 开 始 的 画 数 "用 来 作为 缓存 键 。 同 样 键 名 是 可 以 手动 设置 的 。 
键 名 串联 成 一 个 字符 串 ， 这 样 能 够 用 于 避免 同样 的 块 在 不 同 模版 被 重复 计算 。 


设置 timeout 为 None， 并 且 使 用 了 自 定义 的 键 : 


{% cache None "key" 96)... 


为 了 删除 缓存 值 ， 为 “de 设置 超时 时 间 : 


{% cache 'del' 96)... 


如 果 提 供 键 名 ， 你 可 以 很 容易 地 产生 模版 的 片段 密 钥 ， 从 模板 上 下 文 外 删除 它 : 


from flask.ext.cache import make template fragment key 
key = make template fragment key("key1", vary on-["key2", "key3"]) 
cache.delete(key) 


例子 : 
Considering we have render form field and render submit macroses. 
(96 cache 60*5 %} 
«form» 
(96 render form field form.username %} 
(96 render submit %} 


«/form» 


(96 endcache 96) 


iE x 
/月 余 缓存 
请 参看 clear() . 


下 面 的 例子 是 一 个 用 来 清空 应 用 缓存 的 脚本 : 


from flask.ext.cache import Cache 
from yourapp import app, your cache config 
cache - Cache() 


def main(): 
cache.init app(app, config-your cache config) 


with app.app context(): 
cache.clear() 





if name == ' gqmain ': 
main() 
Warning 


某 些 缓存 类 型 不 支持 完全 清空 缓存 。 同 祥 ， 如 果 你 不 使 用 键 前 级 ， 一 些 缓存 类 型 将 刷新 整个 
数据 库 。 请 确保 你 没有 任何 其 他 数据 存储 在 缓存 数据 库 中 。 


配置 Flask-Cache 


Flask-Cache 有 下 面 一 些 配 置 项 : 


CACHE_TYPE 


旨 定 哪些 类 型 的 缓存 对 象 来 使 用 。 这 是 一 个 输入 字符 串 ， 将 被 导入 并 实例 化 。 它 假设 被 导入 
的 对 象 是 一 个 依赖 于 werkzeug 缓 存 API， 返回 缓存 对 象 的 函数 。 


对 于 werkzeug.contrib.cache 对 象 ， 不 必 给 出 完整 的 字符 串 ， 只 要 是 下 列 这 些 名 称 之 一 。 


e null: NullCache (default) 

e simple: SimpleCache 

e memcached: MemcachedCache (pylibmc or memcache required) 
e gaememcached: GAEMemcachedCache 

e redis: RedisCache (Werkzeug 0.7 required) 

e filesystem: FileSystemCache 

e saslmemcached: SASLMemcachedCache (pylibmc required) 


CACHE NO NULL. WARNING 当 使 用 的 缓存 类 型 是 ,nul， 不 会 抛 出 警告 信息 。 


可 选 的 列表 ， 在 缓存 类 实例 化 的 时 候 会 对 该 列表 进行 拆 分 
以 及 传递 〈 传 参 ) 。 


可 选 的 字典 ， 在 缓存 类 实例 化 的 时 候 会 传递 该 字典 ( 传 
参 ) 。 


如 果 没 有 设置 延迟 时 间 ， 默 认 的 延 时 时 间 会 被 使 用 。 单 位 
为 秒 。 


最 大 的 缓存 条 目 数 ， 超 过 该 数 会 删除 一 些 缓存 条 目 。 仅 仅 
用 于 SimpleCache 和 FileSystemCache。 


所 有 键 之 前 添加 的 前 级 。 这 使 得 它 可 以 为 不 同 的 应 用 程序 
CACHE_KEY_PREFIX 使 用 相同 的 memcached 服 务 器 。 仅仅 用 于 RedisCache， 
MemcachedCache 以 及 GAEMemcachedCache。 
CACHE. MEMCACHED SERVERS 服务 器 地 址 列表 或 元 组 。 仅 用 于 MemcachedCache。 


SASL 与 memcached 服 务 器 认证 的 用 户 名 。 信用 于 


CACHE_ARGS 


CACHE. OPTIONS 


CACHE DEFAULT TIMEOUT 


CACHE THRESHOLD 


CACHE MEMCACHED USERNAME 


SASLMemcachedCache, 
DRCHEZHEHGHCHENNPESEVEINS SASL 与 nemcached 服 务 器 认证 的 密码 。 仅 用 于 
SASLMemcachedCache。 
CACHE_REDIS_HOST Redis 服 务 器 的 主机 。 仅 用 于 RedisCache。 
CACHE_REDIS_PORT Redis 服 务 器 的 端口 。 上 默认 是 6379。 仅 用 于 RedisCache。 
CACHE_REDIS_PASSWORD 用 于 Redis 服 务 器 的 密码 。 仅 用 于 RedisCache。 
RO Redis 的 db 库 (基于 需 号 素 引 )。 默 认 是 0。 仅 用 于 
RedisCache, 
CACHE. DIR 存储 缓存 的 目录 。 仅 用 于 FileSystemCache。 
连接 到 Redis 服 务 器 的 URL。 例 
CACHE_REDIS_URL 如 : redis://user:password@localhost:6379/2 。 仅 用 于 
RedisCache。 


此 外 ， 如 果 标 准 的 Flask 配 置 项 TESTIN6 使 用 并 且 设 置 为 True 的 话 ， Flask-Cache 将 只 会 使 
用 NullCache 作 为 缓存 类 型 。 


内 建 的 缓存 类 型 


NullCache - null 


不 缓存 内 容 


e CACHE ARGS 
e CACHE OPTIONS 


SimpleCache - simple 
使 用 本 地 Python 字典 缓存 。 这 不 是 真正 的 线程 安全 。 
相关 配置 


e CACHE DEFAULT. TIMEOUT 
e CACHE, THRESHOLD 

e CACHE ARGS 

e CACHE, OPTIONS 


FileSystemCache - filesystem 


使 用 文件 系统 来 存储 缓存 值 


e CACHE_DEFAULT_TIMEOUT 
e CACHE DIR 

e CACHE, THRESHOLD 

e CACHE ARGS 

e CACHE, OPTIONS 


MemcachedCache — memcached 


使 用 memcached 服 务 器 作为 后 端 。 支 持 pylibmc 或 memcache 或 谷歌 应 用 程序 引擎 的 
memcache X , 


相关 配置 项 


e CACHE_DEFAULT_TIMEOUT 

e CACHE KEY. PREFIX 

e CACHE MEMCACHED SERVERS 
e CACHE ARGS 

e CACHE. OPTIONS 


GAEMemcachedCache - gaememcached 


MemcachedCache — 4^ [8] B5 4 fl 


SASLMemcachedCache - sasimemcached 


使 用 memcached 服 务 器 作为 后 端 。 使 用 SASL 建 立 与 memcached 服 务 器 的 连接 。pylibmc 是 必 
须 的 ，libmemcached 必 须 支持 SASL。 


相关 配置 项 


e CACHE_DEFAULT_TIMEOUT 

e CACHE KEY. PREFIX 

e CACHE MEMCACHED SERVERS 
e CACHE MEMCACHED USERNAME 
e CACHE MEMCACHED PASSWORD 
e CACHE ARGS 

e CACHE, OPTIONS 


New in version 0.10. 


SpreadSASLMemcachedCache — 
spreadsaslImemcachedcache 


与 SASLMemcachedCache 一 样 ， 但 是 如 果 大 于 memcached 的 传输 安全 性 ， 默 认 是 1M， 能 够 
跨 不 同 的 键 名 缓存 值 。 使 用 pickle 模 块 。 


New in version 0.11. 


RedisCache - redis 


e CACHE DEFAULT. TIMEOUT 
e CACHE KEY. PREFIX 

e CACHE REDIS HOST 

。 CACHE REDIS PORT 

e CACHE REDIS PASSWORD 
e CACHE REDIS DB 

e CACHE ARGS 

e CACHE. OPTIONS 

e CACHE REDIS URL 


XE TER Und) 
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数 。 cAcHE TYPE 将 是 你 自 定义 的 函数 名 的 字符 串 。 这 个 函数 期 望 得 到 三 个 参数 。 


e app 
© args 


*  kwargs 


你 自 定 义 的 缓存 对 象 必 须 是 werkzeug.contrib.cache.BaseCache 的 子 类 。 确保 threshold 是 
包含 在 kwargs 参 数 中 ， 因 为 它 是 所 有 BaseCache 类 通用 的 。 


Redis 的 缓存 实现 的 一 个 例子 : 


#: the app/custom.py 
class RedisCache(BaseCache): 
def _ init (self, servers, default timeout-500): 
pass 


def redis(app, config, args, kwargs): 


args.append(app.config['REDIS SERVERS']) 
return RedisCache(*args, **kwargs) 


在 这 个 例子 中 ， cAcHE_TYPE 可 能 就 是 the app.custom.redis o 


PylibMC 缓 存 实现 的 一 个 例子 : 


#: the_app/custom.py 
def pylibmccache(app, config, args, kwargs): 
return pylibmc.Client(servers-config['CACHE MEMCACHED SERVERS'], 
username-config['CACHE MEMCACHED USERNAME'], 
password-zconfig['CACHE MEMCACHED PASSWORD'], 
binary-True) 


在 这 个 例子 中 ， CACHE_TYPE 可 能 就 是 the app.custom.pylibmccache o 


API 


class flask.ext.cache.Cache(appzNone, with jinja2 ext-True, config=None) 


This class is used to control the cache objects. 


add(*args, **kwargs) 


Proxy function for internal cache object. 


cached(timeout=None, key_prefix='view/%s', unless=None) 


Decorator. Use this to cache a function. By default the cache key is view/request.path . You 
are able to use this decorator with any function by changing the key. prefix . If the token 
%s is located within the key prefix then it will replace that with request.path 


Example: 


# An example view function 
@cache.cached(timeout=50) 
def big foo(): 

return big bar calc() 


# An example misc function to cache. 
Qcache.cached(key prefix-'MyCachedList') 
def get list(): 
return [random.randrange(O, 1) for i in range(50000)] 


my list - get list() 


Note 
You MUST have a request context to actually called any functions that are cached. 


New in version 0.4: The returned decorated function now has three function attributes 
assigned to it. These attributes are readable/writable. 


uncached 
The original undecorated function 
cache timeout 


The cache timeout value for this function. For a custom value to take affect, this must be set 
before the function is called. 


make cache key 
A function used in generating the cache key used. 
Parameters: 


e timeout — Default None. If set to an integer, will cache for that amount of time. Unit of 
time is in seconds. 
e key prefix — 


Default ‘view/%(request.path)s’. Beginning key to . use for the cache key. 


New in version 0.3.4: Can optionally be a callable which takes no arguments but retur 
4 Ix ANE 2m: > | 


o unless — Default None. Cache will always execute the caching facilities unless this 






callable is true. This will bypass the caching entirely. 

clear() 
Proxy function for internal cache object. 

delete(*args, **kwargs) 
Proxy function for internal cache object. 

delete many(*args, **kwargs) 

Proxy function for internal cache object. 

delete memoized(f, *args, **kwargs) 


Deletes the specified functions caches, based by given parameters. If parameters are given, 
only the functions that were memoized with them will be erased. Otherwise all versions of 
the caches will be forgotten. 


Example: 


Qcache.memoize(50) 
def random func(): 
return random.randrange(1, 50) 


Qcache.memoize() 
def param func(a, b): 
return at+tb+random.randrange(1, 50) 


>>> random func() 

43 

>>> random func() 

43 

>>> cache.delete memoized('random func') 
>>> random func() 

16 

>>> param func(1, 2) 

32 

>>> param func(1, 2) 

32 

>>> param func(2, 2) 

47 

>>> cache.delete memoized('param func', 1, 2) 
>>> param func(1, 2) 

13 

>>> param func(2, 2) 

47 


Delete memoized is also smart about instance methods vs class methods. 


When passing a instancemethod, it will only clear the cache related to that instance of that 
object. (object uniqueness can be overridden 


When passing a classmethod, it will clear all caches related across all instances of that 
class. 


Example: 


class Adder (object): 

Qcache.memoize() 

def add(self, b): 
return b + random.random( ) 


>>> adderi = Adder() 

>>> adder2 = Adder() 

>>> adder1.add(3) 

3.23214234 

>>> adder2.add(3) 

3.60898509 

>>> cache.delete memoized(adder.add) 
>>> adderi.add(3) 

3.01348673 

>>> adder2.add(3) 

3.60898509 

>>> cache.delete memoized(Adder.add) 
>>> adderi.add(3) 

3.53235667 

>>> adder2.add(3) 

3.72341788 


Parameters: 


e fname — Name of the memoized function, or a reference to the function. 
e *args — A list of positional parameters used with memoized function. 
e **kwargs — A dict of named parameters used with memoized function. 


Note 


Flask-Cache uses inspect to order kwargs into positional args when the function is 
memoized. If you pass a function reference into fname instead of the function name, Flask- 
Cache will be able to place the args/kwargs in the proper order, and delete the positional 
cache. 


However, if delete memoized is just called with the name of the function, be sure to pass in 
potential arguments in the same order as defined in your function as args only, otherwise 
Flask-Cache will not be able to compute the same cache key. 


Note 


Flask-Cache maintains an internal random version hash for the function. Using 
delete memoized will only swap out the version hash, causing the memoize function to 
recompute results and put them into another key. 


This leaves any computed caches for this memoized function within the caching backend. 


It is recommended to use a very high timeout with memoize if using this function, so that 
when the version has is swapped, the old cached results would eventually be reclaimed by 
the caching backend. 


delete memoized verhash(f, *args) 
Delete the version hash associated with the function. 


..Warning: 


Performing this operation could leave keys behind that have 

been created with this version hash. It is up to the application 
to make sure that all keys that may have been created with this 
version hash at least have timeouts so they will not sit orphaned 
in the cache backend. 


get(*args, **kwargs) 

Proxy function for internal cache object. 
get many(*args, **kwargs) 

Proxy function for internal cache object. 
init app(app, config=None) 


This is used to initialize cache with your app object 


memoize(timeout=None, make_name=None, unless=None) 
Use this to cache the result of a function, taking its arguments into account in the cache key. 
Information on Memoization. 


Example: 


@cache.memoize(timeout=50) 
def big foo(a, b): 
return a * b * random.randrange(0, 1000) 


>>> big foo(5, 2) 
753 
>>> big foo(5, 3) 
234 
>>> big foo(5, 2) 
753 


New in version 0.4: The returned decorated function now has three function attributes 
assigned to it. 


uncached 
The original undecorated function. readable only 
cache_timeout 


The cache timeout value for this function. For a custom value to take affect, this must be set 
before the function is called. 


readable and writable 


make_cache_key 


A function used in generating the cache key used. 
readable and writable 
Parameters: 


e timeout — Default None. If set to an integer, will cache for that amount of time. Unit of 
time is in seconds. 

e make name - Default None. If set this is a function that accepts a single argument, the 
function name, and returns a new string to be used as the function name. If not set then 
the function name is used. 

e unless — Default None. Cache will always execute the caching facilities unelss this 
callable is true. This will bypass the caching entirely. 


New in version 0.5: params make name , unless 
set(*args, **kwargs) 

Proxy function for internal cache object. 

set many(*args, **kwargs) 


Proxy function for internal cache object. 


Changelog 


Version 0.13 2014-04-21 


e Port to Python >= 3.3 (requiring Python 2.6/2.7 for 2.x). 

e Fixed bug with using per-memoize timeouts greater than the default timeout 
e Added better support for per-instance memoization. 

e Various bug fixes 


Version 0.12 2013-04-29 


e Changes jinja2 cache templates to use stable predictable keys. Previously the key for a 
cache tag included the line number of the template, which made it difficult to predict 
what the key would be outside of the application. 

e Adds config variable cacuE No NuLL waRNING to silence warning messages when using 
'null' cache as part of testing. 

e Adds passthrough to clear entire cache backend. 


Version 0.11.1 2013-04-7 


e Bugfix for using memoize on instance methods. The previous key was id(self), the new 
key is repr(self) 


Version 0.11 2013-03-23 


e Fail gracefully in production if cache backend raises an exception. 

e Support for redis DB number 

e Jinja2 templatetag cache now concats all args together into a single key instead of 
treating each arg as a separate key name. 

e Added delete memcache version hash function 

e Support for multiple cache objects on a single app again. 

e Added SpreadSASLMemcached, if a value is greater than the memcached threshold 
which defaults to 1MB, this splits the value across multiple keys. 

e Added support to use URL to connect to redis. 


Version 0.10.1 2013-01-13 


e Added warning message when using cache type of ‘null’ 
e Changed imports to relative instead of absolute for AppEngine compatibility 


Version 0.10.0 2013-01-05 


e Added saslmemcached backend to support Memcached behind SASL authentication. 
e Fixes a bug with memoize when the number of args != number of kwargs 


Version 0.9.2 2012-11-18 


e Bugfix with default kwargs 


Version 0.9.1 2012-11-16 


e Fixes broken memoized on functions that use default kwargs 


Version 0.9.0 2012-10-14 


e Fixes memoization to work on methods. 


Version 0.8.0 2012-09-30 


e Migrated to the new flask extension naming convention of flask cache instead of 
flaskext.cache 


e Removed unnecessary dependencies in setup.py file. 
e Documentation updates 


Version 0.7.0 2012-08-25 


e Allows multiple cache objects to be instantiated with different configuration values. 


Version 0.6.0 2012-08-12 


e Memoization is now safer for multiple applications using the same backing store. 
e Removed the explicit set of NullCache if the Flask app is set testing- True 
e Swapped Conditional order for key prefix 


Version 0.5.0 2012-02-03 


e Deleting memoized functions now properly functions in production environments where 
multiple instances of the application are running. 

e get memoized names and get memoized keys have been removed. 

e Added make name to memoize, make name is an optional callable that can be passed 
to memoize to modify the cache key that gets generated. 

e Added unless to memoize, this is the same as the unless parameter in cached 

e memoization now converts all kwargs to positional arguments, this is so that when a 
function is called multiple ways, it would evaluate to the same cache key 


Version 0.4.0 2011-12-11 


e Added attributes for uncached, make cache key, cache timeout to the decorated 
functions. 


Version 0.3.4 2011-09-10 


e UTF-8 encoding of cache key 
e key prefix argument of the cached decorator now supports callables. 


Version 0.3.3 2011-06-03 


Uses base64 for memoize caching. This fixes rare issues where the cache key was either a 
tuple or larger than the caching backend would be able to support. 


Adds support for deleting memoized caches optionally based on function parameters. 


Python 2.5 compatibility, plus bugfix with string.format. 


Added the ability to retrieve memoized function names or cache keys. 


Version 0.3.2 


Bugfix release. Fixes a bug that would cause an exception if no cAcHE_TYPE was supplied. 


Version 0.3.1 
Pypi egg fix. 


Version 0.3 


e CACHE TYPE changed. Now one of [‘null’, ‘simple’, ‘memcached’, 'gaememcached', 
‘filesystem’], or an import string to a function that will instantiate a cache object. This 
allows Flask-Cache to be much more extensible and configurable. 


Version 0.2 


e CACHE TYPE now uses an import string. 
e Added CACHE OPTIONS and CACHE ARGS configuration values. 
e Added delete memoized 


Version 0.1 


e Initial public release 


在 Flask 中 使 用 Celery 


Flask + Celery Examples 


Example 1: Send Asynchronous Email 
Send test email to; miguel.grinberg@gmail.com 


Send Send in 1 minute 


Example 2: Long running task with progress updates 


Start Long Calculation 


Loading harmonic bit... 


Loading radiant particle reshaper... 


Repairing master bit... 





后 台 运 行 任务 的 话题 是 有 些 复 条 ， 因 为 围绕 这 个 话题 会 让 人 产生 困惑 。 为 了 简单 起 见 ， 在 以 
前 我 所 有 的 例子 中 ， 我 都 是 在 线程 中 执行 后 台 任 务 ， 但 是 我 一 直 注 意 到 更 具有 扩展 性 以 及 具 
备 生 产 解决 方案 的 任务 队列 像 Celery 应 该 可 以 替代 线程 中 执行 后 台 任 务 。 


不 断 有 读者 问 我 关于 Celery 问题 ， 以 及 怎样 在 Flask 应 用 中 使 用 它 ， 因 此 今天 我 将 会 向 你 们 
展示 两 个 例子 ， 我 希望 能 够 履 盖 大 部 分 的 应 用 需求 。 


什么 是 Celery? 


Celery 是 一 个 异步 任务 队列 。 你 可 以 使 用 它 在 你 的 应 用 上 下 文 之 外 执行 任务 。 总 的 想法 就 是 
你 的 应 用 程序 可 能 需要 执行 任何 消耗 资源 的 任务 都 可 以 交 给 任务 队列 ， 让 你 的 应 用 程序 自由 
和 快速 地 响应 客户 端 请 求 。 


使 用 Celery 运行 后 台 任 务 并 不 像 在 线程 中 这 样 做 那么 简单 。 但 是 好 处 多 多 ，Celery 具有 分 布 
式 架 构 ， 使 你 的 应 用 易于 扩展 。 一 个 Celery 安装 有 三 个 核心 组 件 : 


1. Celery 客户 端 : 用 于 发 布 后 台 作 业 。 当 与 Flask 一 起 工作 的 时 候 ， 客 户 端 与 Flask 应 用 一 
起 运行 。 


2. Celery workers: 这 些 是 运行 后 台 作 业 的 进程 。Celery 支持 本 地 和 远程 的 workers， 因 此 
你 就 可 以 在 Flask 服务 器 上 启动 一 个 单独 的 worker， 随 后 随 着 你 的 应 用 需求 的 增加 而 新 
增 更 多 的 workers。 

3. 消息 代理 : 客户 端 通过 消息 队列 和 workers 进行 通信 ，Celery 支持 多 种 方式 来 实现 这 些 队 
列 。 最 常用 的 代理 就 是 RabbitMQ 和 Redis。 


致 行动 派 读 者 


如 果 你 是 行动 派 ， 本 文 开头 的 截图 勾 起 你 的 好 奇 心 的 话 ， 那 么 可 以 直接 到 Github repository 
获取 本 文 用 到 的 代码 。 README 文件 将 会 给 你 快速 和 直接 的 方式 去 运行 示例 应 用 。 


接着 可 以 回 到 本 文 来 了 解 工作 机 制 ! 


Flask 和 Celery 一 起 工作 


Flask 与 Celery 整合 是 十 分 简单 ， 不 需要 任何 插件 。 一 个 Flask 应 用 需要 使 用 Celery 的 话 只 
需要 初始 化 Celery 客户 端 像 这 样 : 


from flask import Flask 
from celery import Celery 


app = Flask( name ) 


app.config['CELERY BROKER URL'] = 'redis://localhost:6379/0' 
app.config['CELERY RESULT BACKEND'] = 'redis://localhost:6379/0' 


celery - Celery(app.name, broker-app.config['CELERY BROKER URL']) 
celery.conf.update(app.config) 


正如 你 所 见 ，Celery 通过 创建 一 个 Celery 类 对 象 来 初始 化 ， 传 人 应 用 名 称 以 及 消息 代理 的 连 
接 URL， 这 个 URL 我 把 它 放 在 app.config 中 的 CELERY BROKER URL 的 键 值 。URL 告 

诉 Celery 代理 服务 在 哪里 运行 。 如 果 你 运行 的 不 是 Redis， 或 者 代理 服务 运行 在 一 个 不 同 的 
机 器 上 ， 相 应 地 你 需要 改变 URL. 


Celery 其 它 任何 配置 可 以 直接 用 celery.conf.update() 通过 Flask 的 配置 直接 传递 。 
CELERY_RESULT_BACKEND 选项 只 有 在 你 必须 要 Celery 任务 的 存储 状态 和 运行 结果 的 时 
候 才 是 必须 的 。 展 示 的 第 一 个 示例 是 不 需要 这 个 功能 的 ， 但 是 第 二 个 示例 是 需要 的 ， 因 此 最 
好 从 一 开始 就 配置 好 。 


任何 你 需要 作为 后 台 任 务 的 函数 需要 用 celery.task 装饰 器 装饰 。 例 如 : 


Qcelery.task 

def my background task(argi, arg2): 
# some long running task here 
return result 


接着 Flask 应 用 能 够 请 求 这 个 后 台 任 务 的 执行 ， 像 这 样 : 


task = my background task.delay(10, 20) 


delay() 方法 是 强大 的 apply async() 调用 的 快捷 方式 。 这 样 相当 于 使 用 apply. async(): 


task = my background task.apply async(args-[10, 20]) 


当 使 用 apply_async()， 你 可 以 给 Celery 后 台 任 务 如 何 执行 的 更 详细 的 说 明 。 一 个 有 用 的 选 
项 就 是 要 求 任 务 在 未 来 的 某 一 时 刻 执行 。 例 如 ， 这 个 调用 将 安排 任务 运行 在 大 约 一 分 钟 后 : 


task = my_background_task.apply_async(args=[10, 20], countdown=60) 


delay() 和 apply_async() 的 返回 值 是 一 个 表示 任务 的 对 象 ， 这 个 对 象 可 以 用 于 获取 任务 状 
态 。 我 将 会 在 本 文 的 后 面 展示 如 何 获取 任务 状态 等 信息 ， 但 现在 让 我 们 保持 简单 些 ， 不 用 担 
心 任务 的 执行 结果 。 


更 多 可 用 的 选项 请 参阅 Celery 文档 。 


简单 例子 : 异步 发 送 邮 件 
我 要 闪 的 第 一 个 示例 是 占用 程序 非常 普通 的 需求 : 能 够 发 送 邮件 但 是 不 阻塞 主 点 用 。 
在 这 个 例子 中 我 会 用 到 Flask-Mail 扩展 ， 我 会 假设 你 们 熟悉 这 个 扩展 。 


我 用 来 说 明 的 示例 应用 是 一 个 只 有 一 个 输入 文本 框 的 简单 表单 。 要 求 用 户 在 此 文本 框 中 输入 
一 个 电子 邮件 地 址 ， 并 在 提交 ， 服 务 器 会 发 送 一 个 测试 电子 邮件 到 这 个 邮件 地 址 。 表 单 中 包 
含 两 个 提交 按钮 ， 一 个 立即 发 送 邮 件 ， 一 个 是 一 分 钟 后 发 送 邮 件 。 表 单 的 截图 在 文章 开始 。 


这 里 就 是 支持 这 个 示例 的 HTML 模板 : 


«html» 
«head» 
<title>Flask + Celery Examples</title> 
</head> 
<body> 
<hi>Flask + Celery Examples</h1> 
<h2>Example 1: Send Asynchronous Email</h2> 
{% for message in get_flashed_messages() %} 
<p style="color: red;">{{ message }}</p> 
{% endfor %} 
<form method="POST"> 
<p>Send test email to: <input type="text" name="email" value="{{ email }}"></p> 
<input type="submit" name-z"submit" value="Send"> 
<input type="submit" name="submit" value="Send in 1 minute"> 
</form> 
</body> 
</html> 


这 里 没有 什么 特别 的 东西 。 只 是 一 个 普通 的 HTML 表单 ， 再 加 上 Flask 闪现 消息 。 


Flask-Mail 扩展 需要 一 些 配 置 ， 尤 其 是 电子 邮件 服务 器 发 送 邮 件 的 时 候 会 用 到 一 些 细节 。 为 了 
简单 我 使 用 我 的 Gmail 账号 作为 邮件 服务 器 : 


4 Flask-Mail configuration 

app.config['MAIL SERVER'] - 'smtp.googlemail.com' 
app.config['MAIL PORT'] - 587 

app.config['MAIL USE TLS'] - True 

app.config['MAIL USERNAME'] = os.environ.get('MAIL USERNAME!) 
app.config['MAIL PASSWORD'] = os.environ.get('MAIL PASSWORD!) 
app.config['MAIL DEFAULT SENDER'] = 'flask@example.com' 


注意 为 了 避免 我 的 账号 技 失 的 风险 ， 我 将 其 设置 在 系统 的 环境 变量 ， 这 是 我 从 应 用 中 导入 
的 。 


有 一 个 单一 的 路 由 来 支持 这 个 示例 : 


Qapp.route('/', methods-['GET', 'POST']) 
def index(): 
if request.method -- 'GET': 
return render template('index.html', email-session.get('email', '')) 
email - request.form['email'] 
session['email'] - email 


4 send the email 
msg = Message('Hello from Flask', 
recipients-[request.form['email']]) 

msg.body - 'This is a test email sent from a background Celery task.' 
if request.form['submit'] -- 'Send': 

# send right away 

send async email.delay(msg) 

flash('Sending email to {0}'.format(email) ) 
else: 

# send in one minute 

send async email.apply async(args-[msg], countdown-60) 

flash('An email will be sent to {0} in one minute'.format(email) ) 


return redirect(url for('index')) 


再 次 说 明 ， 这 是 一 个 很 标准 的 Flask 应 用 。 由 于 这 是 一 个 非常 简单 的 表单 ， 我 决定 在 没有 扩 
展 的 帮助 下 人 处理 它 ， 因 此 我 用 request.method 和 request.form 来 完成 所 有 的 管理 。 我 保存 用 
户 在 文本 框 中 输入 的 值 在 session 中 ， 这 样 在 页 面 重新 加 载 后 就 能 记 住 它 。 


在 这 个 函数 中 让 人 有 兴趣 的 是 发 送 邮 件 的 时 候 是 通过 调用 一 个 叫做 send_async_email 的 
Celery 任务 ， 该 任务 调用 delay() 或 者 apply_async() 方法 。 


这 个 应 用 的 最 后 一 部 分 就 是 能 够 完成 作业 的 异步 任务 : 


Qcelery.task 
def send async email(msg): 
"""Background task to send an email with Flask-Mail.""" 
with app.app context(): 
mail.send(msg) 


这 个 任务 使 用 celery.task 装饰 使 得 成 为 一 个 后 台 作 业 。 这 个 函数 唯一 值得 注意 的 就 是 Flask- 
Mail 需要 在 应 用 的 上 下 文中 运行 ， 因 此 需要 在 调用 send() 之 前 创建 一 个 应 用 上 下 文 。 


重点 注意 在 这 个 示例 中 从 异步 调用 返回 值 并 不 保留 ， 因 此 应 用 不 能 知道 调用 成 功 或 者 失败 。 
当 你 运行 这 个 示例 的 时 候 ， 需 要 检查 Celery worker 的 输出 来 排查 发 送 邮 件 的 问题 。 


复 杀 例子 : 显示 状态 更 新 和 结果 


上 面 的 示例 过 于 简单 ， 后 台 作 业 启 动 然后 应 用 忘记 它 。 大 部 分 Celery 针对 网 页 开发 的 教程 就 
到 此 为 止 ， 但 是 事实 上 许多 应 用 程序 有 必要 监控 它 的 后 台 任 务 并 且 获 取 运 行 结果 。 


我 现在 将 要 做 的 就 是 扩展 上 面 的 应 用 程序 成 为 第 二 个 示例 ， 这 个 示例 展示 一 个 虚构 的 长 时 间 
运行 的 任务 。 用 户 点 击 按钮 启动 一 个 或 者 更 多 的 长 时 间 运 行 的 任务 ， 在 浏览 器 上 的 页 面 使 用 
ajax 轮 询 服务 器 更 新 所 有 任务 的 状态 。 每 一 个 任务 ， 页 面 都 会 显示 一 个 图 形 的 状态 栏 ， 进 度 
条 ， 一 个 状态 消息 ， 并 且 当 任务 完成 的 时 候 ， 也 会 显示 任务 的 执行 结果 。 示 例 的 截图 在 本 文 
的 最 开始 。 


状态 更 新 的 后 台 任 务 
让 我 向 你 们 展示 我 在 第 二 个 示例 中 使 用 的 后 台 任务 


@celery.task(bind=True) 
def long task(self): 
""Background task that runs a long function with progress reports.""" 
verb - ['Starting up', 'Booting', 'Repairing', 'Loading', 'Checking'] 


adjective 三 Lewes 'radiant', 'silent', 'harmonic', 'fast'] 
noun = [' Solar array', 'particle reshaper', 'cosmic ray', 'orbiter', 'bit'] 
message - ' 


total - random.randint(10, 50) 
for i in range(total): 
if not message or random.random() « 0.25: 
message = '(0) {1} {2}...'.format(random.choice(verb), 
random.choice(adjective), 
random.choice(noun) ) 
self .update_state(state='PROGRESS', 


meta={'current': i, 'total': total, 
'status': message}) 
time.sleep(1) 


return {'current': 100, 'total': 100, 'status': 'Task completed!', 
'result': 42} 


对 于 这 个 任务 ， 我 在 Celery 装饰 器 中 添加 了 bind=True 参数 。 这 个 参数 告诉 Celery 发 送 一 个 
self 参数 到 我 的 函数 ， 我 能 够 使 用 它 (self) 来 记录 状态 更 新 。 


因为 这 个 任务 真 没 有 干什么 有 用 的 事情 ， 我 决定 使 用 随机 的 动词 ， 形 容 词 和 名 词组 合 的 幽 黑 
状态 信息 。 你 可 以 在 代码 上 看 到 我 用 来 生成 上 述 信 息 的 毫 无 意义 的 列表 。 


self.update state() 调用 是 Celery 如 何 接 受 这 些 任务 更 新 。 有 一 些 内 置 的 状态 。 上 比如 
STARTED, SUCCESS 等 等 ， 但 是 Celery 也 支持 自 定义 状态 。 这 里 我 使 用 一 个 叫做 
PROGRESS 的 自 定义 状态 。 连 同 状态 。 还 有 一 个 附件 的 元 数据 ， 该 元 数据 是 Python 字典 形 
式 ， 包 含 目 前 和 总 的 迭代 数 以 及 随机 生成 的 状态 消息 。 客 户 端 可 以 使 用 这 些 元 素来 显示 一 个 
漂亮 的 进度 条 。 每 迭代 一 次 休眠 一 秒 ， 以 模拟 正在 做 一 些 工作 。 


当 循 环 退 出 ， 一 个 Python 字典 作为 画 数 结果 返回 。 这 个 字典 包含 了 更 新 迭代 计数 器 ， 最 后 的 
状态 消息 和 幽默 的 结果 。 


上 面 的 long task() 函数 在 一 个 Celery worker 进程 中 运行 。 下 面 你 能 看 到 和 启动 这 个 后 台 作 业 
的 Flask 应 用 路 由 : 


Qapp.route('/longtask', methods=['POST']) 
def longtask(): 
task - long task.apply async() 
return jsonify({}), 202, {'Location': url for('taskstatus', 
task id-task.id)) 


正如 你 所 见 ， 客 户 端 需要 发 起 一 个 POST 请 求 到 /longtask 来 掀 开 这 些 任务 中 的 一 个 的 序幕 。 
服务 器 启动 任务 ， 并 且 存 储 返 回 值 。 对 于 响应 我 使 用 状态 码 202， 这 个 状态 码 通常 是 在 REST 
APIs 中 使 用 用 来 表明 一 个 请 求 正在 进行 中 。 我 也 添加 了 Location 头 ， 值 为 一 个 客户 端 用 来 获 
取 状 态 信 息 的 URL。 这 个 URL 指向 另 一 个 叫做 taskstatus 的 Flask 路 由 ， 并 且 有 task.id 作 


M Flask 应 用 中 访问 任务 状态 
上 面 提 及 到 taskstatus 路 由 负责 报告 有 后 台 任 务 提供 的 状态 更 新 。 这 里 就 是 这 个 路 由 的 实现 : 


@app.route('/status/<task_id>' ) 
def taskstatus(task_id): 
task = long task.AsyncResult(task id) 
if task.state -- 'PENDING': 
// job did not start yet 
response - ( 
'state': task.state, 
'current': 0, 


Bota IT 
'status': 'Pending...' 
} 
elif task.state != 'FAILURE': 


response = { 
"state': task.state, 
'current': task.info.get('current', 0), 
'total': task.info.get('total', 1), 
'status': task.info.get('status', '') 


if 'result' in task.info: 

response['result'] - task.info['result'] 
else: 

# something went wrong in the background job 

response - ( 
'state': task.state, 
'current': 1, 
bibotad er 
'status': str(task.info), # this is the exception raised 


return jsonify(response) 


这 个 路 由 生成 一 个 JSON 响应 ， 该 响应 包含 任务 的 状态 以 及 设置 在 update state() 调用 中 作 
为 meta 的 参数 的 所 有 值 ， 客 户 端 可 以 使 用 这 些 构 建 一 个 进度 条 。 遗 憾 地 是 这 个 函数 需要 检查 
一 些 条 件 ， 因 此 代码 有 些 长 。 为 了 能 够 访问 任务 的 数据 ， 我 重新 创建 了 任务 对 象 ， 该 对 象 是 


AsyncResult 类 的 实例 ， 使 用 了 URL 中 给 的 任务 id. 


第 一 个 if 代码 块 是 当 任 务 还 没有 开始 的 时 候 (PENDING 状态 )。 在 这 种 情况 下 暂时 没有 状态 信 
息 ， 因 此 我 人 为 地 制造 了 些 数据 。 接 下 来 的 elif 代码 块 返回 后 台 的 任务 的 状态 信息 。 任 务 提供 
的 信息 可 以 通过 访问 task.info 获得 。 如 果 数 据 中 包含 键 result, ， 这 就 意味 着 这 是 最 终 的 结 
并 且 任 务 已 经 结束 ， 因 此 我 把 这 些 信息 也 加 到 响应 中 。 最 后 的 else 代码 块 是 任务 执行 失败 的 
情况 ， 这 种 情况 下 task.info 中 会 包含 异常 的 信息 。 


不 管 你 是 否 相 信 ， 服 务 器 所 有 要 做 的 事情 已 经 完成 了 。 剩 下 的 部 分 就 是 需要 客户 端 需要 实现 
的 ， 在 这 里 也 就 是 用 JavaScript 脚本 的 网 页 来 实现 。 


客户 端的 Javascript 
这 一 部 分 就 不 是 本 文 的 重点 ， 如 果 你 有 兴趣 的 话 ， 可 以 自己 研究 研究 。 


对 于 图 形 进度 条 我 使 用 nanobarjs， 我 从 CDN 上 引用 它 。 同 祥 还 需要 引入 jQuery， 它 能 够 简 
化 ajax 的 调用 。 


«script srcz"//cdnjs.cloudflare.com/ajax/libs/nanobar/0.2.1/nanobar.min.js"»«/script» 
«script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script> 


启动 连接 后 台 作 业 的 按钮 的 Javascript 义理 程序 如 下 : 


function start long task() { 
// add task status elements 
div = $('0%...&nbsp;<hr>'); 
$('#progress').append(div); 


// create a progress bar 
var nanobar = new Nanobar({ 

bg: '#44f', 

target: div[0].childNodes[0] 
1; 


// send ajax POST request to start background job 
$.ajax(1 
type: 'POST', 
url: '/longtask', 
success: function(data, status, request) { 
status url = request.getResponseHeader('Location'); 
update progress(status url, nanobar, div[0]); 
3 
error: function() { 
alert('Unexpected error'); 
} 


3); 


div 的 代码 : 


<-- Progress bar 
0% <-- Percentage 
ees <-- Status message 
&nbsp; <-- Result 


<hr> 


最 后 Javascript 的 update progress AX 540 F: 


function update_progress(status_url, nanobar, status div) { 
// send GET request to status URL 
$.getJSON(status url, function(data) ( 
// update UI 
percent - parseInt(data['current'] * 100 / data['total']); 
nanobar.go(percent); 
$(status div.childNodes[1]).text(percent + '%'); 
$(status div.childNodes[2]).text(data['status']); 
if (data['state'] != 'PENDING' && data['state'] != 'PROGRESS') ( 
if ('result' in data) { 
// show result 
$(status div.childNodes[3]).text('Result: ' + data['result']); 
j 
else { 
// something unexpected happened 
$(status div.childNodes[3]).text('Result: ' + data['state']); 
j 
} 
else { 
// rerun in 2 seconds 
setTimeout(function() { 
update progress(status url, nanobar, status div); 
), 2000); 


H; 
这 一 部 分 的 代码 就 不 一 一 解释 了 。 


运行 示例 
首先 下 载 代码 ， 代 码 的 位 于 Github repository， 接 着 执行 以 下 的 命 倒 : 


$ git clone https://github.com/miguelgrinberg/flask-celery-example.git 
$ cd flask-celery-example 

$ virtualenv venv 

$ source venv/bin/activate 

(venv) $ pip install -r requirements.txt 


Ñ 


RUE, 启动 redis， 关 于 redis 的 安装 ， 和 启动 以 及 配置 ， 请 参阅 Redis 文档 。 


最 后 ， 执 行 如 下 命令 运行 示例 : 


$ export MAIL_USERNAME=<your -gmail-username> 

$ export MAIL PASSWORD-«your-gmail-password» 

$ source venv/bin/activate 

(venv) $ celery worker -A app.celery --loglevel-info 


运行 你 的 Flask 应 用 来 感受 Flask 和 Celery 一 起 工作 的 快乐 : 


$ source venv/bin/activate 
(venv) $ python app.py 


欢迎 来 到 Flask_Dashed 的 文档 ! 


Flask-Dashed 提供 构建 简单 以 及 具有 扩展 性 的 管理 界面 的 工具 。 


在 线 演示 : http://flask-dashed.jeanphi.fr/ (需要 Github 账号 )。 
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pip install Flask-Dashed 


最 小 的 使 用 
代码 : 
from flask import Flask 


from flask dashed.admin import Admin 


app = Flask( name ) 
admin - Admin(app) 


ABE name == ' main ': 
app.run() 





示例 应 用 程序 : http://github.com/jeanphix/flask-dashed-demo 


安全 地 人 处理 
保 折 (“ 武 装 ”) 所 有 模块 端 : 


from flask import session 


book module = admin.register module(BookModule, '/books', 'books', 
"book management') 


Qbook module.secure(http code-401) 


def login required(): 
return "user" in session 


DRAP (GERE ) EXE PTS cm: 


Qbook module.secure endpoint('edit', http code-403) 
def check edit credential(view): 
4 I'm now signed in, may I modify the ressource? 
return session.user.can edit book(view.object) 


模块 组 织 
由 于 管理 节点 (node ) 注 册 到 一 个 “ 树 ”， 因 此 很 容易 地 管理 它们 。 


library = admin.register node('/library', 'library', my library) 
book module - admin.register module(BookModule, '/books', 'books', 
'book management', parent-library) 


为 了 满足 你 的 需求 ， 导 航 和 面包 悄 会 自动 地 建立 。 子 模块 的 安全 将 会 继承 自 父 模 块 。 


SQLALchemy 扩展 
Code: 


from flask_dashed.ext.sqlalchemy import ModelAdminModule 
class BookModule(ModelAdminModule): 

model - Book 

db session - db.session 


book module - admin.register module(BookModule, '/books', 'books', 
"book management') 


Api 


Admin 对 象 


class admin.Admin(app, url prefix-'/admin', title-'flask-dashed', main dashboardzNone, end 
Class that provides a way to add admin interface to Flask applications. 
Parameters: 


e app- The Flask application 

e url prefix — The url prefix 

e main dashboard - The main dashboard object 
e endpoint — The endpoint 


add path security(path, function, http code-403) 
Registers security function for given path. 
Parameters: 


e path — The endpoint to secure 
e function — The security function 
e http code - The response http code 


check path security(path) 
Checks security for specific and path. 
Parameters: path — The path to check 

register module(module class, url prefix, endpoint, short title, title-None, parent=None) 
Registers new module to current admin. 

register node(url prefix, endpoint, short title, title=None, parent=None, node class-«clas 
Registers admin node. 


Parameters: 


e url prefix — The url prefix 

e endpoint — The endpoint 

e short title — The short title 

e title — The long title 

e parent — The parent node path 

e node class - The class for node objects 


Admin 模块 


admin.recursive getattr(obj, attr) 


Returns object related attributes, as its atemplate filter None is return when attribute 
doesn't exists. 


eg: 


a = object() 

a.b = object() 

a.b.c =1 
recursive_getattr(a, 'b. 
recursive_getattr(a, 'b. 


c') => 1 
d') => None 


class admin.AdminNode(admin, url_prefix, endpoint, short_title, title=None, parent=None) 
An AdminNode just act as navigation container, it doesn’t provide any rules. 
Parameters: 


e admin — The parent admin object 

e url prefix — The url prefix 

e enpoint — The endpoint 

e short title — The short module title use on navigation & breadcrumbs 
e title — The long title 

e parent — The parent node 


parents 


Returns all parent hierarchy as list. Usefull for breadcrumbs. 


secure(http code-403) 

Gives a way to secure specific url path. 

Parameters: http code — The response http code when False 
url path 


Returns the url path relative to admin one. 


class admin.AdminModule(*args, **kwargs) 
Class that provides a way to create simple admin module. 
Parameters: 


e admin — The parent admin object 

e url prefix — The url prefix 

e enpoint — The endpoint 

e short title — the short module title use on navigation & breadcrumbs 
e title — The long title 

e parent — The parent node 


add url rule(rule, endpoint, view func, **options) 


Adds a routing rule to the application from relative endpoint. view class is copied as we 
need to dynamically apply decorators. 


Parameters: 


e rule — The rule 
e endpoint — The endpoint 
e view func — The view 


secure endpoint(endpoint, http code-403) 
Gives a way to secure specific url path. 
Parameters: 


e endpoint — The endpoint to protect 
e http code - The response http code when False 


url 


Returns first registered (main) rule as url. 


SQLAIchemy 扩展 


class ext.sqlalchemy.ModelAdminModule(*args, **kwargs) 


SQLAlIchemy model admin module builder. 


count list(searchzNone) 
Counts filtered list. 


Parameters: search — The string for quick search 


create object() 


New object instance new object. 


delete object(object) 
Deletes object. 


Parameters: object — The object to delete 


edit query factory 


Returns query for object edition. 


form view 


alias of ObjectFormView 


get actions for object(object) 
"Returns actions for object as and tuple list. 
Parameters: object — The object 
get object(pk) 
Gets back object by primary key. 
Parameters: pk — The object primary key 
get object list(search-zNone, order by namecNone, order by direction-zNone, offset-None, lim 
Returns ordered, filtered and limited query. 
Parameters: 


e search - The string for search filter 
e order by name - The field name to order by 
e order by direction — The field direction 
e offset — The offset position 
e limit — The limit 
list query factory 


Returns non filtered list query. 


save object(obj) 
Saves object. 


Parameters: object — The object to save 


Flask-DebugToolbar 


该 扩展 为 Flask 应 用 程序 添加 了 一 个 包含 有 用 的 调试 信息 的 工具 栏 。 


eoe E] § cC» 127.0.0.1 © 由 DO o» e 


Flaskr 





Unbelievable. No entries here so far 


ch J+ 
安装 
简单 地 使 用 pip 来 安装 : 


$ pip install flask-debugtoolbar 


用 法 


设置 调试 工具 栏 是 简单 的 : 


from flask import Flask 
from flask debugtoolbar import DebugToolbarExtension 


app - Flask( name ) 


4 the toolbar is only enabled in debug mode: 
app.debug - True 


# set a 'SECRET KEY' to enable the Flask session cookies 
app.config['SECRET KEY'] = '<replace with a secret key>' 


toolbar - DebugToolbarExtension(app) 


当 调 试 模式 开启 的 时 候 ， 工 具 栏 会 自动 地 给 添加 到 Jinja 模板 中 。 在 生产 环境 中 ， 
app.debug = False 将 会 禁用 工具 ijt. 


该 扩展 也 支持 Flask 应 用 的 工厂 模式 ， 先 单独 地 创建 工具 栏 接着 后 面 为 应 用 初始 化 它 


toolbar = DebugToolbarExtension() 
4 Then later on. 

app = create app('the-config.cfg') 
toolbar.init app(app) 


Ac is 


工具 栏 支 持 多 个 配置 选项 : 
名 称 描述 默认 值 
DEBUG TB ENABLED 启用 工具 栏 ? app . debug 


显示 工具 栏 的 hosts A 


DEBUG_TB_HOSTS 任意 host 


单 
DEBUG TB INTERCEPT REDIRECTS 要 拦截 重 定 向 ? True 
DEBUG_TB_PANELS 面板 的 模板 /类 名 的 清 允许 所 有 内 置 的 面板 
DEBUG TB PROFILER ENABLED 启用 所 有 请 求 的 分 析 工 具 pees , 用 户 自行 开 
DEBUG_TB_TEMPLATE_EDITOR_ENABLED 启用 模板 编辑 器 False 
要 更 改 配置 选项 之 一 ， 在 Flask 应 用 程序 配置 中 像 这 样 设置 它 : 


app.config['DEBUG TB INTERCEPT REDIRECTS'] = False 


AEH Panels 


版 本 


flask debugtoolbar.panels.versions.VersionDebugPanel 


显示 已 安装 的 Flask 版 本 。 展开 的 视图 显示 了 由 setuptools 发 现 的 所 有 已 安装 的 包 和 它们 的 
版 本 。 


时 间 


flask debugtoolbar.panels.timer.TimerDebugPanel 


显示 处 理 当 前 请 求 的 时 间 。 展 开 后 的 视图 包含 了 用 户 态 和 系统 态 ， 执 行 时 间 ， 上 下 文 切换 的 
CPU 时 间 分 解 。 


Resource Usage Hide » 


Versions 


Resource Value 

User CPU 12.783 msec 
time 

System CPU 2.289 msec 
time 


Total CPU 15.072 msec 
time HTTP Headers 


Elapsed 17.563 msec 
time Request Vars 


Context 3 voluntary, 92 involuntary ; 
switches Config 


HTTP 3. 


flask debugtoolbar.panels.headers.HeaderDebugPanel 


显示 了 目前 请 求 的 HTTP 头 。 


HTTP Headers Hide » 


Versions 
Key Value 
CONTENT. TYPE 
HTTP. ACCEPT text/html,application/xhtml-«xml ,applict 


HTTP ACCEPT. ENCODING gzip, deflate 
HTTP ACCEPT LANGUAGE en-us 


HTTP. CONNECTION keep-alive HTTP Headers 

HTTP. HOST 127.0.0.1:5000 

HTTP_USER_AGENT Mozilla/S.@ (Macintosh; Intel Mac OS X Request Vars 
AppleWebKit/600.2.5 (KHTML, like Gecko: 


Safari/600.2.5 Config 
QUERY_STRING 





in mme 
Request 7 = 
flask debugtoolbar.panels.request vars.RequestVarsDebugPanel 


展现 了 Flask 请 求 相 关 的 变量 的 细节 ， 包 含 视图 函数 变量 ， 会 话 变量 ， 以 及 GET 和 POST € 


Eo 


Request Vars Hide » 


Versions 


View information 


View Function args kwargs 
__main__.show_entries [] None 


Variable a R equest Vars 
'fldt'  u'hide' 

i Config 
SESSION Variables 
No SESSION data Templates 
GET Variables 
No GET data SQLAlchemy 
POST Variables | 
No POST data Logging 





Ac iS 


flask debugtoolbar.panels.config vars.ConfigVarsDebugPanel 


显示 了 Flask 应 用 程序 配置 字典 app.config HAA. 


Config Hide » 





Key Value Versions 
APPLICATION_ROOT None 

DATABASE '/tmp/flaskr .db' 

DEBUG True 

DEBUG. TB. ENABLED True 

DEBUG. TB. HOSTS O HTTP Headers 
DEBUG_TB_INTERCEPT_REDIRECTS True 

DEBUG_TB_PANELS C' flask debugtoolbar.panels.vt Request Vars 
JSON. AS. ASCII True 

JSON. SORT. KEYS True Config 
JSONIFY PRETTYPRINT REGULAR True 

LOGGER. NAME ' main..." Templates 
MAX. CONTENT. LENGTH None 1 RENDERE 
PASSWORD ‘default’ 

DEDMANCAIT COCCTON 1 TECTTME datatiman +imadaltafl2iy SQLAIchem 


模板 
flask debugtoolbar.panels.template.TemplateDebugPanel 


显示 关于 为 某 个 请 求 泻 染 模板 的 信息 ， 以 及 提供 的 模板 参数 的 值 。 


Templates ne 
Versions 

show_entries.html Fiasx 0.10 

Variable Value 

entries [] 

g «flask.g of 'flaskr'» 


request «Request 'http://127.0.0.1:5000/' [GET]» 
session <SecureCookieSession {}> 





SQLAIchemy 
flask debugtoolbar.panels.sqlalchemy.SQLAlchemyDebugPanel 
显示 了 当前 请 求 过 程 中 运行 的 SQL 查询 。 


Note 


为 了 记录 查询 ， 这 个 面板 需要 使 用 Flask-SQLAIchemy 扩展 。 请 查看 Flask-SQLAlchemy 的 
Quickstart 章节 来 配置 它 。 


更 多 关于 查询 记录 的 信息 请 查看 文档 get debug queries() o 


SQLAIchemy queries Hide » 


Versions 


(ms) Action Context Query 


0.2339 ./flaskr.py:71 select title, text from entries 
Cshow entries) 





日 志 


flask debugtoolbar.panels.logger.LoggingPanel 


显示 了 当前 请 求 的 日 志 信息 


Log Messages Hide » 
Version 
Level Time Message Location d 
Fia i D 1 
DEBUG 2015-01-08 Logging ./flaskr.py:67 
16:13:12.271858 message 





路 由 列表 


flask debugtoolbar.panels.route list.RouteListDebugPanel 


显示 了 Flask URL 路 由 规则 。 


分 析 / 探 查 


flask debugtoolbar.panels.profiler.ProfilerDebugPanel 


报告 当前 请 求 的 分 析 / 探 查 数据 。 由 于 性 能 的 考虑 ， 默 认 情 况 下 分 析 / 探 查 是 禁用 的 。 单 击 点 中 
选择 分 析 / 探 查 的 标记 来 决定 开启 或 者 关闭 。 在 启用 分 析 / 探 查 后 ， 重 新 刷新 页 面 来 运行 分 析 / 探 


查 。 


View: 1.25ms 


Calls Total 
+ Time + 
(ms) 
1 0.185 
1 9.11 
5 0.065 
2 0.037 
10 0.031 
5 0.031 
0.031 
` 
AR 


Per 
Call + 
(ms) 
0.1850 
0.1100 
0.0130 
0.0185 
0.0031 
0.0062 
0.0155 


Fork 我 们 在 GitHub 上 。 


感谢 


Cumulative 
Time (ms) + 


0.185 
0.11 

0.075 
0.152 
0.557 
0.053 
0.128 


Function 


{method 'execu 
{-sqlite3. conn 
<werkzeug/urls 
<werkzeug/urls 
./templates/la 
./templates/sh 
«werkzeug/rout 





Hide » 


Versions 


Logging 


Profiler 


COM 


本 扩展 是 基于 django-debug-toolbar 。 多 谢 Michael van Tellingen 为 了 这 个 Flask 扩展 最 初 
的 开发 ， 并 且 感 谢 individual contributors 中 的 每 一 个 人 。 


Flask-Exceptional 
Flask-Exceptional 为 Flask 添加 了 Exceptional xx Rr, Exceptional 会 捕获 到 你 的 应 用 程序 中 


的 错误 ， 实 时 地 报告 它们 ， 并 且 会 收集 你 需要 快速 地 修复 它们 的 一 些 信息 。 访 问 
http://www.exceptional.io 去 试 试 。 


ro AE 

BRR 

接 下 来 的 文档 是 假设 你 拥有 一 个 Exceptional 账号 。 用 pip 安装 这 个 扩展 是 简单 的 : 
$ pip install Flask-Exceptional 


或 者 用 easy install 安装 它 : 


$ easy install Flask-Exceptional 


快速 入 门 


在 安装 Flask-Exceptional 后 ， 所 有 你 必须 要 做 的 就 是 创建 一 个 Flask 应 用 程序 ， 配 置 
Exceptional API 密 钥 ， 接 着 创建 Exceptional 对 象 。 正 是 这 样 的 简单 : 

from flask import Flask 

from flask.ext.exceptional import Exceptional 


app = Flask( name ) 
app.config["EXCEPTIONAL API KEY"] - "exceptional forty character unique key" 
exceptional - Exceptional(app) 


你 的 应用 程序 是 被 配置 成 基于 云 的 错误 监控 1 你 可 以 通过 调用 Exceptional.test() 方法 来 验 
证 配置 是 否 正常 工作 : 


Exceptional.test(app.config) 


请 翻阅 接 下 来 的 章节 获取 更 多 关于 Flask-Exceptional 可 用 的 配置 项 的 细节 。 


Boi 


Flask-Exceptional 中 存在 如 下 的 配置 项 : 


你 的 应 用 程序 的 Exceptional API 密 钥 。 登录 到 
Exceptional， 选 择 你 的 应 用 程序 ， 点 击 APP 

EXCEPTIONAL API KEY SETTINGS 链接 。 显 示 的 API 密 钥 就 是 这 里 要 用 到 
的 。 试图 不 提供 API 密 钥 而 创建 扩展 将 导致 SERE 
告 ， 但 应 用 程序 将 继续 正常 运行 。 


如 果 你 的 应 用 程序 以 调式 模式 运行 的 话 ， 
Exceptional 将 不 会 捕获 错误 。 配 置 这 个 值 是 为 
调试 模式 中 捕获 错误 数据 。 比如 ， 你 可 能 使 用 一 

SA EE ES RequestBin 网 址 调试 你 的 应 用 程序 。JSON pu 
据 会 被 以 压缩 形式 POSTed 到 这 个 网 址 ， 而 
Exceptional 需要 解压 这 些 数据 。 


EXCESTIONALHTTEUEODES FA Exceptional 追踪 的 HTTP 错误 码 列 表 。 默 认为 标 
MERI HTTP 4xx 错误 码 。 


列表 值 ， 用 来 过 滤 发 给 Exceptional 的 参数 数据 。 参 
数 数据 包括 request.form 和 request.files 中 的 
所 有 。 例 如 ， 为 了 过 滤 密 码 你 可 以 使 


FA: ['password', 'password_confirm' ] 


列表 值 ， 用 来 过 滤 发 给 Exceptional 的 环境 数据 。 环 
境 数据 包含 Flask 应 用 程序 配置 以 及 目前 OS 环境 。 
OS 环境 值 前 级 是 'os.' 。 例 如 ， 为 了 过 滤 
EXCEPTIONAL_ENVIRONMENT_FILTER SQLAlchemy 数据 库 URL 以 及 所 有 的 OS 环境 入 
使 用 : ['SQLALCHEMY. DATABASE URI', 'os.*'] 默认 值 


EXCEPTIONAL_PARAMETER_FILTER 


是  ['SECRET KEY'] o 
EXCEPTIONAL SESSION FILTER 列表 值 ， 用 来 过 滤 发 给 Exceptional 的 会 话 数 据 。 
EXCEPTIONAL_HEADER_FILTER 用 来 过 滤 发 给 Exceptional 的 HTTP 头 数 


EXCEPTIONAL. COOKIE FILTER 名 称 的 列表 ， 用 来 过 滤 发 给 Exceptional 的 HTTP 
Cookie 头 数据 。 
Note 


所 有 配置 中 的 过 滤 列 表 接 受 字符 串 以 及 正则 表达 式 。 


API 


class flask.ext.exceptional.Exceptional(app-None) 


Extension for tracking application errors with Exceptional. Errors are not tracked if DEBUG is 
True. The application will log a warning if no ExcEPTIONAL API kEv has been configured. 


Parameters: 


app — Default None. The Flask application to track errors for. If the app is not provided on 
creation, then it can be provided later via init app(). 


static context(data=None, **kwargs) 


Add extra context data to the current tracked exception. The context data is only valid for the 
current request. Multiple calls to this method will update any existing context with new data. 


Parameters: 


e data — Default None . A dictionary of context data. 
e **kwargs — A series of keyword arguments to use as context data. 


init app(app) 
Initialize this Exceptional extension. 


Parameters: 


app — The Flask application to track errors for. 


static publish(config, traceback) 


Publish the given traceback directly to Exceptional. This method is useful for tracking errors 
that occur outside the context of a Flask request. For example, this may be called from an 
asynchronous queue. 


Parameters: 


e config — A Flask application configuration object. Accepts either flask.config orthe 
object types allowed by flask.Config.from_object() . 
e traceback — A werkzeug.debug.tbtools.Traceback instance to publish. 


static test(config) 


Test the given Flask configuration. If configured correctly, an error will be tracked by 
Exceptional for your app. Unlike the initialized extension, this test will post data to 
Exceptional, regardless of the configured pegue setting. 


Parameters: 


config — The Flask application configuration object to test. Accepts either flask.config Or 
the object types allowed by flask.Config.from_object() . 


Changelog 


Version 0.5.4 


e Updated JSON implementation import to work with Flask 0.10. 


Version 0.5.3 


e Fixed Exceptional.publish() to no longer dereference a request context. 


Version 0.5.2 


e Unwind broken app ctx stack usage. 


Version 0.5.1 


e Handle malformed HTTP response status-line from Exceptional. 


Version 0.5 


e Updated with Flask 0.8 extension structure recommendations and 0.9 app ctx stack. 
e Added ([('application environment': 'loaded libraries': {...}} API data. 


Version 0.4.9 


e Added the Exceptional,context() method to support Exceptional's extra context data 
API. 
e Updated to reference the new exceptional.io domain. 


Version 0.4.8 


e Updated to publish UTF-8 encoded data to Exceptional. 
e Added support for request.json data. 


Version 0.4.7 


e Added the Exceptional.publish() method to support Exceptional tracking outside the 
context of a request. 


Version 0.4.6 


e Corrected occurred at timestamp to be formatted as Zulu. 
e Fixed JSON serialization issue by coercing all environment variables to strings. 


Version 0.4.5 


e Updated to log a warning on repeated extension initialization attempts. 


Version 0.4.4 


e Fixed to workaround Python 2.5 issue where urlopen() raises a HTTPError even 
though the HTTP response code indicates success. 


Version 0.4.3 


e Changed so that app.extensions['exceptional'] targets the Exceptional extension 
instance. 


Version 0.4.2 


e Updated to support Python 2.5. 


Version 0.4.1 


e Updated to support Flask 0.7 blueprints. 


Version 0.4 


e Updated to support Python 2.6. 
e Added eEXcEPTIONAL_DEBUG_URL testing environment variable override. 


Version 0.3 


e Updated to handle unreachable Exceptional service API. 


Version 0.2 


e Added eExceptional.test() method. 


Version 0.1 


e Initial public release. 


Flask-Login 


Flask-Login 为 Flask 提供 了 用 户 会 话 管理 。 它 义理 了 日 常 的 登入 ， 登 出 并 且 长 时 间 记 住 用 户 
的 会 话 。 


mA. 
ba: 


在 会 话 中 存储 当前 活跃 的 用 户 ID， 让 你 能 够 自由 地 登入 和 登 出 。 
让 你 限制 登 人 (或 者 登 出 ) 用 户 可 以 访问 的 视图 。 

KIRLA RFA “eR” 功能。 

帮助 你 保护 用 户 会 话 免 遭 cookie 被 资 的 牵连 。 

可 以 与 以 后 可 能 使 用 的 Flask-Principal 或 其 它 认 证 扩展 集成 。 


但 是 ， 它 不 会 : 


限制 你 使 用 特定 的 数据 库 或 其 它 存储 方法 。 如 何 加 载 用 户 完 全 由 你 决定 。 
限制 你 使 用 用 户 名 和 密码 ，OpenlDs， 或 者 其 它 的 认证 方法 。 

义理 超越 “登入 或 者 登 出 ” 之 外 的 权限 。 

处 理 用 户 注 册 或 者 账号 恢复 。 


配置 你 的 应 用 
它 是 如 何 工作 
你 的 用 户 类 
Login 示例 
定制 登入 过 程 
使 用 授权 头 (Authorization header) 登 录 
使 用 Request Loader 定制 登录 
匿名 用 户 
记 住 我 
o Ait The 
o "新 鲜 的 “登录 (Fresh Logins) 
o Cookie 设置 
会 话 保护 
本 地 化 
API 文档 
o 配置 登录 
o 登录 机 制 
o 保护 视图 
o 用 户 对 象 助 手 
o 工具 


[LL 


aS 


o 
— 


Acie (RAY 3 FA 


对 一 个 使 用 Flask-Login 的 应 用 最 重要 的 一 部 分 就 是 LoginManager 类 。 你 应 该 在 你 的 代码 的 
某 处 为 应 用 创建 一 个 ， 像 这 样 : 


login manager = LoginManager() 


登录 管理 (login manager) 包 含 了 让 你 的 应 用 和 Flask-Login 协同 工作 的 代码 ， 上 比如 怎样 从 一 个 
ID 加 载 用 户 ， 当 用 户 需 要 登录 的 时 候 跳 转 到 哪里 等 等 。 


一 旦 实际 的 应 用 对 象 创建 后 ， 你 能 够 这 样 配置 它 来 实现 登录 : 


login manager.init app(app) 


它 是 如 何 工作 


你 必须 提供 一 个 user_loader 回调 。 这 个 回调 用 于 从 会 话 中 存储 的 用 户 ID 重新 加 载 用 户 对 
象 。 它 应 该 接受 一 个 用 户 的 unicode ID 作为 参数 ， 并 且 返 回 相 应 的 用 户 对 象 。 上 比如 : 


Qlogin manager.user loader 
def load user(userid): 
return User.get(userid) 


如 果 ID 无 效 的 话 ， 它 应 该 返回 None (而 不 是 抛 出 异常 )。( 在 这 种 情况 下 ，ID 会 被 手动 从 会 
话 中 移 除 且 义理 会 继续 ) 


你 的 用 户 类 


你 用 来 表示 用 户 的 类 需要 实现 这 些 属性 和 方法 : 

is authenticated 

当 用 户 通过 验证 时 ， 也 即 提供 有 效 证 明 时 返回 True o (只 有 通过 验证 的 用 户 会 满足 
login required 的 条 件 。 ) 

is active 

如 果 这 是 一 个 活动 用 户 且 通 过 验证 ， 账 户 也 已 激活 ， 未 被 停 用 ， 也 不 符合 任何 你 的 应 用 拒绝 
一 个 账号 的 条 件 ， 返 回 True 。 不 活动 的 账号 可 能 不 会 登入 (当然 ， 是 在 没 被 强制 的 情况 
下 ) o 


is anonymous 


如 果 是 一 个 匿名 用 户 ， 返 回 True 。 (真实 用 户 应 返回 False o ) 


get id() 


返回 一 oa 一 识别 用 户 的 ， 并 能 用 于 从 user 1oader 回调 中 加 载 用 户 的 unicode 。 注 意 
着 必须 是 一 unicode 如 果 ID 原本 是 一 个 int 或 其 它 类 型 ， 你 需要 把 它 转 换 为 


unicode o 





要 简便 地 实现 用 户 类 ， 你 可 以 从 usermixin 继承 ， 它 提供 了 对 所 有 这 些 方法 的 默认 实现 。 
(虽然 这 不 是 必须 的 。 ) 


Login 示例 
一 旦 用 户 通过 验证 ， 你 可 以 使 用 1login_user WAILA PSS. PA: 


Qapp.route('/login', methods=['GET', 'POST']) 
def login(): 
# Here we use a class of some kind to represent and validate our 
# client-side form data. For example, WTForms is a library that will 
# handle this for us, and we use a custom LoginForm to validate. 
form = LoginForm() 
if form.validate on submit(): 
# Login and validate the user. 
# user should be an instance of your "User! class 
login user(user) 


flask.flash('Logged in successfully.') 


next - flask.request.args.get('next') 
# next is valid should check if the user has valid 
# permission to access the “next> url 
if not next is valid(next): 
return flask.abort(400) 


return flask.redirect(next or flask.url for('index')) 
return flask.render template('login.html', form-form) 


警告 : 你 必须 验证 next 参数 的 值 。 如 果 不 验 证 的 话 ， 你 的 应 用 将 会 受到 重 定向 的 攻击 。 
就 这 么 简单 。 你 可 用 使 用 current user 代理 来 访问 登录 的 用 户 ， 在 每 一 个 模板 中 都 可 以 使 用 


current user : 


(96 if current user.is authenticated() %} 
Hi {{ current user.name }}! 
(96 endif %} 


需要 用 户 登 入 的 视图 可 以 用 login required 装饰 器 来 装饰 : 


Qapp.route("/settings") 
Qlogin required 
def settings(): 

pass 


当 用 户 要 登 出 时 : 


Qapp.route("/logout") 
login required 
def logout(): 
logout user() 
return redirect(somewhere) 


他 们 会 被 登 出 ， 且 他 们 会 话 产生 的 任何 cookie 都 会 被 清理 干净 。 


定制 登 人 过 if 


默认 情况 下 ， 当 未 登录 的 用 户 尝试 访问 一 个 1ogin required 装饰 的 视图 ，Flask- -Login 会 闪 
见 一 条 消息 并 且 重 定向 到 登录 视图 。 (如果 未 设置 登录 视图 ， 它 将 会 以 401 错误 退出 。) 


登录 视图 的 名 称 可 以 设置 成 LoginManager.login view 。 例 如 : 


login manager.login view = "users.login" 


默认 的 闪现 消息 是 Please log in to access this page. 。 要 自 定义 该 信息 ， 请 设置 


LoginManager.login message : 


login manager.login message = u"Bonvolu ensaluti por uzi tio paffo." 


要 自 定 义 消 息 分 类 的 话 ， 请 设置 LoginManager.login message category : 
login manager.login message category = "info" 


当 重 定向 到 登入 视图 ， 它 的 请 求 字 符 串 中 会 有 一 个 next 变量 ， 其 值 为 用 户 之 前 访问 的 页 
面 。 


如 果 你 想 要 进一步 自 定义 登入 过 程 ， 请 使 用 LoginManager.unauthorized handler 装饰 图 数 : 


@login_manager .unauthorized_handler 
def unauthorized(): 

# do stuff 

return a_response 


使 用 授权 头 (Authorization header) = x: 


Caution 


该 方法 将 会 被 弃 用 ， 使 用 下 一 节 的 ”request_loader 来 代替。 


有 些 时 候 你 要 支持 使 用 Authorization 头 的 基本 认证 登录 ， 比 如 API 请 求 。 为 了 支持 通过 头 
登录 你 需要 提供 一 个 header loader 回调 。 这 个 回调 和 user_loader 回调 作用 一 样 ， 只 是 它 
接受 一 个 HTTP 关 (Authorization) 而 不 是 用 > id。 例 如 : 


login manager.header loader 
def load user from header(header val): 
header val - header val.replace('Basic ', '', 1) 
try: 
header val - base64.b64decode(header val) 
except TypeError: 
pass 
return User.query.filter by(api key-header val).first() 


默认 情况 下 Authorization 的 值 传 给 header 1oader 回调 。 你 可 以 使 用 AUTH_HEADER_NAME 
配置 来 修改 使 用 的 HTTP 头 ( 可 以 不 使 用 Authorization ， 使 用 Token )。 


使 用 Request Loader 定制 登录 


有 时 你 想 要 不 使 用 cookies 情况 下 登录 用 户 ， 比 如 使 用 HTTP 头 或 者 一 个 作为 查询 参数 的 api 
密 钥 。 这 种 情况 下 ， 你 应 该 使 用 request loader 回调 。 这 个 回调 和 user_loader 回调 作用 
一 样 ， 但 是 user_loader 回调 只 接受 Flask 请 求 而 不 是 一 个 user. id, 


例如 ， 为 了 同时 支持 一 个 url 参数 和 使 用 authorization 头 的 基本 用 户 认证 的 登录 : 


Q1ogin manager.request loader 
def load user from request(request): 


# first, try to login using the api key url arg 
api key = request.args.get('api key!) 
if api key: 
user - User.query.filter by(api key-api key).first() 
if user: 
return user 


# next, try to login using Basic Auth 
api key = request.headers.get('Authorization' ) 
if api key: 
api key - api key.replace('Basic ', '', 1) 
try: 
api key - base64.b64decode(api key) 
except TypeError: 
pass 
user - User.query.filter by(api key-api key).first() 
if user: 
return user 


# finally, return None if both methods did not login the user 
return None 


E HP 


默认 情况 下 ， 当 一 个 用 户 没有 真正 地 登录 ， current_user 被 设置 成 一 个 AnonymoususerMixin 
对 象 。 它 由 如 下 的 属性 和 方法 : 


* is active 和 is authenticated 的 值 为 raise 
e is anonymous 的 值 为 True 
* get id() 返回 None 


如 果 需 要 为 匿名 用 户 定制 一 些 需 求 (比如 ， 需 要 一 个 权限 域 )， 你 可 以 向 Loginmanager 提供 一 
个 创建 匿名 用 户 的 回调 (类 或 工厂 辑 数 ) : 


login manager.anonymous user = MyAnonymousUser 


记 住 我 


“ 记 住 我 "的 功能 很 难 实现 。 但 是 ，Flask-Login 几乎 透明 地 实现 它 - 只 要 把 remember=True 传 
递 给 login user 。 一 个 cookie 将 会 存储 在 用 户 计算 机 中 ， 如 果 用 户 会话 中 没有 用 户 ID 的 
话 ，Flask-Login 会 自动 地 从 cookie 中 恢复 用 户 ID. cookie 是 防 纂 改 的 ， 因 此 如 果 用 户 繁 改 
过 它 ( 比 如 ， 使 用 其 它 的 一 些 东 西 来 代替 用 户 的 ID)， 它 就 会 被 拒绝 ， 就 像 不 存在 。 


该 层 功 能 是 被 自动 实现 的 。 但 你 能 ( 且 应 该 ， 如 果 你 的 应 用 处 理 任何 敏感 的 数据 ) 提供 额外 
基础 工作 来 增强 你 记 住 的 cookie 的 安全 性 。 


DESIT 
使 用 用 户 ID 作为 记 住 的 令 牌 值 不 一 定 是 安全 的 。 更 安全 的 方法 是 使 用 用 户 名 和 密码 联合 的 
hash 值 ， 或 类 似 的 东西 。 要 添加 一 个 额外 的 倒 牌 ， 向 你 的 用 户 对 象 添加 一 个 方法 : 

get auth token() 


返回 用 户 的 认证 合 牌 (返回 为 unicode ) 。 这 个 认证 兮 牌 应 能 唯一 识别 用 户 ， 且 不 易 通 过 用 


识 
户 的 公开 信息 ， 如 UID 和 名 称 来 猜测 出 一 一 同样 也 不 应 暴露 这 些 信息 。 





相应 地 ， 你 应 该 在 LoginManager 上 设置 一 个 token loader BRM, 它 接受 使 牌 (存储 在 
cookie 中 ) 作为 参数 并 返回 合适 的 User 对 象 。 


make secure token KAA FERA 38 3. 3E BE. 它 会 连接 所 有 的 参数 ， 然后 用 应 用 的 密 钥 来 
HMAC 它 确保 最 大 的 密码 学 安全 。 〈 如 果 你 永久 地 在 数据 库 中 存储 用 户 邻 牌 ， 那 么 你 会 希望 
句 令 牌 中 添加 随机 数据 来 阻碍 猜测 。 ) 


如 果 你 的 应 用 使 用 密码 来 验证 用 户 ， 在 认证 兮 牌 中 包含 密码 (或 你 应 使 用 的 加 盐 值 的 密码 
hash ) 能 确保 若 用 户 更 改 密码 ， 他 们 的 旧 认 证 使 牌 会 失效 。 


”新 鲜 的 “登录 (Fresh Logins) 


当 用 户 登入 ， 他 们 的 会 话 被 标记 成 “新鲜 的 "， 就 是 说 在 这 个 会 话 只 中 用 户 实际 上 登录 过 。 当 会 
话 销毁 用 户 使 用 “ 记 住 我 "的 cookie 重新 登入 ， 会 话 被 标记 成 “ 非 新 鲜 的 "。 login required 并 
不 在 意 它们 之 间 的 不 同 ， 这 适用 于 大 部 分 页 面 。 然 而 ， 更 改 某 人 的 个 人 信息 这 样 的 敏感 操作 
应 需要 一 个 新鲜 的 "的 登 人 。 ( 像 修改 密码 这 样 的 操作 总 是 需要 密码 ， 无 论 是 否 重 登 人 。) 

fresh login required ， 除 了 验证 用 户 登 录 ， 也 将 确保 他 们 的 登录 是 “新 鲜 的 "。 如 果 不 是 "新鲜 
的 ”， 它 会 把 用 户 送 到 可 以 重 输 入 验证 条 件 的 页 面 。 你 可 以 定制 fresh login required 就 像 定 
fll login required 那样 ， 通过 设置 LoginManager.refresh view , needs refresh message ， 


和 needs_refresh_message_category : 


login manager.refresh view = "accounts.reauthenticate" 
login manager.needs refresh message - ( 

u"To protect your account, please reauthenticate to access this page." 
) 


login manager.needs refresh message category - "info" 


或 者 提供 自己 的 回调 来 处 理 “ 非 新 鲜 的 "刷新 : 


@login manager.needs refresh handler 
def refresh(): 

4 do stuff 

return a response 


调用 confirm login 回 数 可 以 重新 标记 会 话 为 "新 鲜 “。 
Cookie 设置 
cookie 的 细节 可 以 在 应 用 设置 中 定义 。 


存储 “ 记 住 我 "信息 的 cookie 名 。 默认 值 : 


REMEMBER_COOKIE_NAME 
remember_token 


cookie 过 期 时 间 ， 为 一 个 datetime.timedelta 对 象 。 默 
认 值 : 365 天 (1 非 闽 阳历 年 ) 


如 果 “ 记 住 我 ”cookie 应 跨 域 ， 在 此 处 设置 域名 值 ( 即 


REMEMBER COOKIE DURATION 


REMEMBER COOKIE DOMAIN .example.com 会 允许 example 下 所 有 子 域 E). 默认 
值 : None 
REMEMBER_COOKIE_PATH 限制 ” 记 住 我 * cookie 存储 到 某 一 路 径 下 。 Rita: / 


限制 "Remember Me" cookie 在 某 些 安全 通道 下 有 用 (Hà 
型 地 HTTPS) 。 默 认 值 : None 


保护 "Remember Me" cookie 不 能 通过 客户 端 脚本 访问 。 
默认 值 : False 


REMEMBER_COOKIE_SECURE 


REMEMBER_COOKIE_HTTPONLY 


会 话 保护 


当 上 述 特性 保护 " 记 住 我 ” 令 牌 免 遭 cookie 窃取 时 ， 会 话 cookie 仍然 是 脆弱 的 。 Flask-Login 
包含 了 会 话 保护 来 帮助 阻止 用 户 会 话 被 盗用 。 


你 可 以 在 LoginManager 上 和 应 用 配置 中 配置 会 话 保 折 。 如 果 它 被 启用 ， 它 可 以 在 basic 或 
strong 两 种 模式 中 运行 。 要 在 LoginManager 上 设置 它 ， 设 置 session _protection 属性 为 


"basic" 或 "strong" 


login manager.session protection - "strong" 


XA, RAC: 

login_manager.session_protection = None 
默认 ， 它 被 激活 为 "basic" 模式 。 它 可 以 在 应 用 配置 中 设 定 SESSION PROTECTION 为 None 
* "basic" 或 "strong" 来 禁用 。 


当 咎 用 了 会 话 保 护 ， 每 个 请 求 ， 它 生成 一 个 用 户 电脑 的 标识 〈 基 本 上 是 IP 地 址 和 User Agent 
的 MD5 hash 值 ) 。 如 果 会 话 不 包含 相关 的 标识 ， 则 存储 生成 的 。 如 果 存 在 标识 ， 则 匹配 生 
成 的 ， 之 后 请 求 可 用 。 


在 basic 模式 下 或 会 话 是 永久 的 ， 如 果 该 标识 未 匹配 ， 会 话 会 简单 地 被 标记 为 非 活 路 的 ， 
且 任 何 需要 活路 登入 的 东西 会 强制 用 户 重新 验证 。 (当然 ， 你 必须 已 经 使 用 了 活路 登入 机 制 
才能 奏效 。) 


在 strong 模式 下 的 非 永 久 会 话 ， 如 果 该 标识 未 匹配 ， 整 个 会 话 〈 记 住 的 邻 牌 如 果 存 在 ， 则 
同样 ) 被 副 除 。 


本 地 化 


默认 情况 下 ， 当 用 户 需 要 登录 ， LoginManager 使 用 flah 来 显示 信息 。 这 些 信息 都 是 英文 
的 。 如 果 你 需要 本 地 化 ， 设置 LoginManager 的 localize callback [a tk 25 — I ER qz, 该 函数 
在 消息 被 发 送 到 flash 的 时 候 被 调用 ， 比 如 ， gettext o 


API 文档 
这 部 分 文档 是 从 Flask-Login 源码 中 自动 生成 的 。 


Boi ER Xx 


class flask.ext.login.LoginManager(app-None, add context processor-True) 


This object is used to hold the settings used for logging in. Instances of LoyinManager are 
not bound to specific apps, so you can create one in the main body of your code and then 
bind it to your app in a factory function. 


setup app(app, add context processor-True) 


This method has been deprecated. Please use LoginManager.init app() instead. 


unauthorized() 


This is called when the user is required to log in. If you register a callback with 
LoginManager.unauthorized handler() , then it will be called. Otherwise, it will take the 


following actions: 


e Flash ioginManager.login message to the user. 
e |fthe app is using blueprints find the login view for the current blueprint using 
blueprint login views . If the app is not using blueprints or the login view for the 
current blueprint is not specified use the value of login view . Redirect the user to the 
login view. (The page they were attempting to access will be passed in the next query 
string variable, so you can redirect there if present instead of the homepage.) 


If LoginManager.login view is not defined, then it will simply raise a HTTP 401 
(Unauthorized) error instead. 


This should be returned from a view or before/after request function, otherwise the redirect 
will have no effect. 

needs refresh() 
This is called when the user is logged in, but they need to be reauthenticated because their 


session is stale. If you register a callback with needs refresh handler , then it will be called. 
Otherwise, it will take the following actions: 


e Flash LoginManager.needs refresh message to the user. 

e Redirect the user to LoginManager.refresh_view . (The page they were attempting to 
access will be passed in the next query string variable, so you can redirect there if 
present instead of the homepage.) 


If LoginManager.refresh view is not defined, then it will simply raise a HTTP 401 
(Unauthorized) error instead. 


This should be returned from a view or before/after request function, otherwise the redirect 
will have no effect. 


General Configuration 


user loader(callback) 


This sets the callback for reloading a user from the session. The function you set should 
take a user ID (a unicode ) and return a user object, or None if the user does not exist. 


Parameters: callback (callable) — The callback for retrieving a user object. 
header loader(callback) 


This sets the callback for loading a user from a header value. The function you set should 
take an authentication token and return a user object, or None if the user does not exist. 


Parameters: callback (callable) — The callback for retrieving a user object. 


token loader(callback) 


This sets the callback for loading a user from an authentication token. The function you set 
should take an authentication token (a unicode , as returned by a user's get auth token 
method) and return a user object, or None if the user does not exist. 


Parameters: callback (callable) — The callback for retrieving a user object. 


anonymous user 


A class or factory function that produces an anonymous user, which is used when no one is 
logged in. 


unauthorized Configuration 
login view 


The name of the view to redirect to when the user needs to log in. (This can be an absolute 
URL as well, if your authentication machinery is external to your application.) 


login message 
The message to flash when a user is redirected to the login page. 


unauthorized handler(callback) 


This will set the callback for the unauthorized method, which among other things is used by 
login required . It takes no arguments, and should return a response to be sent to the user 
instead of their normal view. 


Parameters: callback (callable) — The callback for unauthorized users. 


needs refresh Configuration 


refresh view 


The name of the view to redirect to when the user needs to reauthenticate. 


needs refresh message 


The message to flash when a user is redirected to the reauthentication page. 


needs refresh handler(callback) 


This will set the callback for the needs refresh. method, which among other things is used 
by fresh login required . It takes no arguments, and should return a response to be sent to 
the user instead of their normal view. 


Parameters: callback (ca//ab/e) — The callback for unauthorized users. 


登录 机 制 


flask.ext.login.current user 


A proxy for the current user. 


flask.ext.login.login fresh() 


This returns True if the current login is fresh. 


flask.ext.login.login user(user, remember-False, force-False, fresh-True) 


Logs a user in. You should pass the actual user object to this. If the user's is active 
property is False , they will not be logged in unless force is True . 


This will return True if the log in attempt succeeds, and raise if it fails (i.e. because the 
user is inactive). 


Parameters: 


e user (object) — The user object to log in. 

e remember (bool) — Whether to remember the user after their session expires. Defaults 
to False. 

e force (bool) — If the user is inactive, setting this to True will log them in regardless. 
Defaults to False . 

e fresh — setting this to False will log in the user with a session 


marked as not “fresh”. Defaults to True . :type fresh: bool 


flask.ext.login.logout user() 


Logs a user out. (You do not need to pass the actual user.) This will also clean up the 
remember me cookie if it exists. 


lask.ext.login.confirm login() 


This sets the current session as fresh. Sessions become stale when they are reloaded from 
a cookie. 


保护 视 


flask.ext.login.login required(func) 


If you decorate a view with this, it will ensure that the current user is logged in and 
authenticated before calling the actual view. (If they are not, it calls the 
LoginManager.unauthorized callback.) For example: 


Qapp.route('/post') 
login required 
def post(): 

pass 


If there are only certain times you need to require that your user is logged in, you can do so 
with: 


if not current user.is authenticated: 
return current app.login manager.unauthorized() 
...Which is essentially the code that this function adds to your views. 


It can be convenient to globally turn off authentication when unit testing. To enable this, if the 
application configuration variable LoerN prsaBLED is setto True , this decorator will be 
ignored. 


Parameters: func (function) — The view function to decorate. 


flask.ext.login.fresh login required(func) 


If you decorate a view with this, it will ensure that the current user's login is fresh - i.e. there 
session was not restored from a 'remember me' cookie. Sensitive operations, like changing 
a password or e-mail, should be protected with this, to impede the efforts of cookie thieves. 


If the user is not authenticated, LoginManager.unauthorized() is called as normal. If they are 
authenticated, but their session is not fresh, it will call Loginwanager.needs refresh() 
instead. (In that case, you will need to provide a LoginManager .refresh_view .) 


Behaves identically to the login required() decorator with respect to configutation 
variables. 


Parameters: func (function) — The view function to decorate. 


用 户 对 象 助 手 


class flask.ext.login.UserMixin 


This provides default implementations for the methods that Flask-Login expects user objects 
to have. 


工具 
1N 
flask.ext.login.login url(login view, next_url=None, next_field='next') 


Creates a URL for redirecting to a login page. If only 1ogin view is provided, this will just 
return the URL for it. If next ur1 is provided, however, this will append a  next-uRL 
parameter to the query string so that the login view can redirect back to that URL. 


Parameters: 


* login view (sír) - The name of the login view. (Alternately, the actual URL to the login 
view.) 

e next url (sir) - The URL to give the login view for redirection. 

e next field (sir) — What field to store the next URL in. (It defaults to next .) 


flask.ext.login.make secure token(*args, **options) 


This will create a secure token that you can use as an authentication token for your users. It 
uses heavy-duty HMAC encryption to prevent people from guessing the information. (To 
make it even more effective, if you will never need to regenerate the token, you can pass 
some random data as one of the arguments.) 


Parameters: 


e *args — The data to include in the token. 
e **options (kwargs) — To manually specify a secret key, pass key=THE_KEY . Otherwise, 
the current app Secret key will be used. 


{ 


如 何在 你 的 代码 中 使 用 这 些 信号 请 参阅 Flask documentation on signals, 


ra 
Lc] 


ll 


flask.ext.login.user logged in 


当 一 个 用 户 登 入 的 时 候 发 出 。 除 应 用 〈 信 号 的 发 送 者 ) 之 外 ， 它 还 传递 正 登 人 的 用 户 user 


o 


flask.ext.login.user logged out 


当 一 个 用 户 登 出 的 时 候 发 出 。 除 应 用 〈 信 号 的 发 送 者 ) 之 外 ， 它 还 传递 正 登 出 的 用 户 user 
flask.ext.login.user login confirmed 

当 用 户 的 登入 被 证 实 ， 把 它 标记 为 活路 的 。 ( 它 不 用 于 常规 登入 的 调用 。) 它 不 接受 应用 以 
外 的 任何 其 它 参 数 。 


flask.ext.login.user unauthorized 


34 LoginManager 上 的 unauthorized 方法 被 调用 时 发 出 。 它 不 接受 应 用 以 外 的 任何 其 它 参 
数 。 

flask.ext.login.user needs refresh 

34 LoginwManager 上 的 needs refresh 方法 被 调用 时 发 出 。 它 不 接受 应 用 以 外 的 任何 其 它 参 
数 。 

flask.ext.login.session protected 

当 会 话 保护 起 作用 时 ， 且 会 话 被 标记 为 非 活路 或 删除 时 发 出 。 它 不 接受 应 用 以 外 的 任何 其 它 
参数 。 


flask-mail 


ft Web 应 用 中 的 一 个 最 基本 的 功能 就 是 能 够 给 用 户 发 送 邮件 。 


Flask-Mail 扩展 提供 了 一 个 简单 的 接口 ， 可 以 在 Flask 应 用 中 设置 SMTP 使 得 可 以 在 视图 以 
及 脚本 中 发 送 邮 件 信 息 。 


链接 


。 原版 文档 
e ats 
。 更 新 历史 


安装 Flask-Mail 
使 用 pip 或 者 easy_install 安装 Flask-Mail: 


pip install Flask-Mail 


或 者 从 版 本 控制 系统 (github) 中 下 载 最 新 的 版 本 : 


git clone https://github.com/mattupstate/flask-mail.git 
cd flask-mail 
python setup.py install 


如 果 你 正在 使 用 virtualenv， 假 设 你 会 安装 flask-mail 在 运行 你 的 Flask 应 用 程序 的 同一 个 
virtualenv 上 。 


配置 Flask-Mail 


Flask-Mail 使 用 标准 的 Flask 配置 API 进行 配置 。 下 面 这 些 是 可 用 的 配置 型 (每 一 个 将 会 在 文 
档 中 进行 解释 ): 


e MAIL SERVER : 默认 为 "localhost 
。 MAIL_PORT : 默认 为 25 

e MAIL USE TLS : 默认 为 False 

e MAIL USE SSL : 默认 为 False 

e MAIL DEBUG : 默认 为 app.debug 
e MAIL USERNAME : 默认 为 None 


MAIL_PASSWORD : 默认 为 None 

MAIL, DEFAULT. SENDER : 默认 为 None 
MAIL, MAX EMAILS : 默认 为 None 

MAIL SUPPRESS SEND : 默认 为 app.testing 
MAIL, ASCII ATTACHMENTS : 默认 为 False 


另外 ，Flask-Mail 使 用 标准 的 Flask 的 testine 配置 项 用 于 单元 测试 (下 面 会 具体 介绍 


邮件 是 通过 一 个 mail 实例 进行 管理 : 
from flask import Flask 
from flask mail import Mail 


app = Flask( name ) 
mail - Mail(app) 


在 这 个 例子 中 所 有 的 邮件 将 会 使 用 传人 到 mail 实例 中 的 应 用 程序 的 配置 项 进行 发 送 。 


或 者 你 也 可 以 在 应 用 程序 配置 的 时 候 设 置 你 的 mail RAI, 


mail = Mail() 


app - Flask( name ) 
mail.init app(app) 


在 这 个 例子 中 邮件 将 会 使 用 Flask 的 current app 中 的 配置 项 进行 发 送 。 如 果 你 有 


通过 使 用 init app 方法 : 


不 用 配置 项 的 多 个 应 用 运行 在 同一 程序 的 时 候 ， 这 种 设置 方式 是 十 分 有 用 的 ， 


R I ap AH 
为 了 能 够 发 送 邮 件 ， 首 先 需要 创建 一 个 message 实例 : 


from flask mail import Message 


Qapp.route("/") 
def index(): 


msg - Message("Hello", 


sender="from@example.com", 
recipients-["toQexample.com"]) 


你 能 够 设置 一 个 或 者 多 个 收 件 人 : 


msg.recipients = ["you@example.com"] 
msg.add_recipient("somebodyelse@example.com" ) 


如 果 你 设置 了 MAIL DEFAULT SENDER , 就 不 必 再 次 填写 发 件 人 ， 


发 件 人 : 


默认 情况 下 将 会 使 用 配置 


多 个 具 


有 


项 的 


msg = Message("Hello", 
recipients-["toQexample.com"]) 


如 果 sender 是 一 个 二 元 组 ， 它 将 会 被 分 成 姓名 和 邮件 地 址 : 


msg = Message("Hello", 
sender=("Me", "me@example.com") ) 


assert msg.sender == "Me <me@example.com>" 


邮件 内 容 可 以 包含 主体 以 及 /或 者 HTML 


msg.body 
msg.html 


"testing" 
"<b>testing</b>" 


最 后 ， 发 送 邮 件 的 时 候 请 使 用 Flask 应 用 设置 的 mail 实例 : 


mail.send(msg) 


大 量 邮 件 


通常 在 一 个 Web 应 用 中 每 一 个 请 求 会 同时 发 送 一 封 或 者 两 封 邮件 。 在 某 些 特 定 的 场景 下 ， 有 
可 能 会 发 送 数 十 或 者 数 百 封 邮件 ， 不 过 这 种 发 送 工作 会 给 交 离 线 任务 或 者 脚本 执行 。 


在 这 种 情况 下 发 送 邮件 的 代码 会 有 些 不 同 : 


with mail.connect() as conn: 
for user in users: 
message - '... 
subject = "hello, %s" % user.name 
msg - Message(recipients-[user.email], 
body=message, 
subject=subject) 


conn.send(msg) 


与 电子 邮件 服务 器 的 连接 会 一 直 保持 活动 状态 直到 所 有 的 邮件 都 已 经 发 送 完成 后 才 会 关闭 
( 断 开 ) 。 


有 些 邮件 服务 器 会 限制 一 次 连接 中 的 发 送 邮 件 的 上 限 。 你 可 以 设置 重 连 前 的 发 送 邮件 的 最 大 
数 ， 通 过 配置 MAIL MAX EMAILS 。 


附件 


在 邮件 中 添加 附件 同样 非常 简单 : 


with app.open resource("image.png") as fp: 
msg.attach("image.png", "image/png", fp.read()) 


如 果 wArL AsciI ATTACHMENTS 设置 成 True 的 话 ， 文 件 名 将 会 转换 成 ASCII Bg, 当 文件 名 是 
以 UTF-8 编码 的 时 候 ， 使 用 邮件 转发 的 时 候 会 修改 邮件 内 容 并 且 混 淆 Content-Disposition H 
述 ， 这 个 时 候 MAIL_AscII_ATTACHMENTS 配置 项 是 十 分 有 用 的 。 转 换 成 ASCII 的 基本 方式 就 是 
对 non-ASCII 字符 的 去 除 。 任 何 一 个 unicode 字符 能 够 被 NFKD 分 解 成 一 个 或 者 多 个 ASCII 
字符 。 


单元 测试 以 及 禁止 发 送 邮 件 
当 在 单元 测试 中 ， 或 者 在 一 个 开发 环境 中 ， 能 够 禁止 邮件 发 送 是 十 分 有 用 的 。 


如 果 设 置 项 TESTING 设置 成 True, emails 将 会 被 禁止 发 送 。 调 用 send) 发 送 邮 件 实际 上 
不 会 有 任何 邮件 被 发 送 。 


另外 在 测试 环境 之 中 的 话 ， 你 可 以 设置 MAIL suPPREsS sEND 为 True， 这 也 会 有 相同 的 效果 。 
然而 ， 当 单元 测试 的 时 候 追 踪 邮 件 是 否 发 送 成 功 也 是 十 分 有 用 的 。 
为 了 能 够 追踪 发 送 邮 件 的 “轨迹 "， 可 以 使 用 record messages 方法 : 


with mail.record messages() as outbox: 


mail.send message(subject-'testing', 
body='test', 
recipients=emails) 


assert len(outbox) == 1 
assert outbox[0].subject == "testing" 


outbox 是 一 个 43K Message 实例 的 列表 。 
为 了 使 得 上 述 代 码 能 常 运行 ， 必 须 安装 blinker 包 。 
需要 注意 的 是 以 前 的 义理 方式 ， 即 把 outbox 赋予 给 g 对 象 已 经 过 时 。 


头 注入 


为 了 防止 header injection， 尝 试 着 在 邮件 主题 、 发 件 人 或 者 收 件 人 中 使 用 换行 符 将 会 抛 出 


BadHeaderError 异常 。 


New in version 0.4. 


Flask-Mail 现在 通过 email dispatched 信号 开始 支持 信号 量 。 只 要 邮件 被 调度 ， 信 号 就 会 发 
送 ( 即 使 邮件 没有 真正 的 发 送 ， 例 如 ， 在 测试 环境 中 )。 


订阅 email dispatched 信号 的 函数 使 用 Message 实例 作为 第 一 参数 ， Flask app 实例 作为 一 
个 可 选 的 参数 : 


def log message(message, app): 
app.logger.debug(message.subject) 


email dispatched.connect(log message) 


API 


class flask mail.Mail(appzNone) 
Manages email messaging 


Parameters: app - Flask instance 


connect( ) 


Opens a connection to the mail host. 


send(message) 
Sends a single message instance. If TESTING is True the message will not actually be sent. 


Parameters: message — a Message instance. 


send message(*args, **kwargs) 
Shortcut for send(msg). 
Takes same arguments as Message constructor. 


Versionadded: 0.3.5 


class flask mail.Attachment(filename-zNone, content typezNone, data=None, disposition=None, 
Encapsulates file attachment information. 
Versionadded: 
0.3.5 
Parameters: 


e filename — filename of attachment 
e content type — file mimetype 


e data — the raw file data 
e disposition — content-disposition (if any) 


class flask mail.Connection(mail) 


Handles connection to host. 


send(message, envelope from-zNone) 
Verifies and sends message. 
Parameters: 
e message — Message instance. 
e envelope from — Email address to be used in MAIL FROM command. 


send message(*args, **kwargs) 
Shortcut for send(msg). 
Takes same arguments as Message constructor. 


Versionadded: 0.3.5 


class flask mail.Message(subject-'', recipients=None, body=None, html=None, senderzNone, c: 
Encapsulates an email message. 
Parameters: 


e subject — email subject header 

e recipients — list of email addresses 

e body - plain text message 

e html — HTML message 

e sender — email sender address, or MAIL DEFAULT SENDER by default 
e cc — CC list 

e bcc — BCC list 

e attachments - list of Attachment instances 

e reply to — reply-to address 

e date — send date 

e charset — message character set 

e extra headers — A dictionary of additional headers for the message 

e mail options — A list of ESMTP options to be used in MAIL FROM command 
e rcpt options — A list of ESMTP options to be used in RCPT commands 


add recipient(recipient) 
Adds another recipient to the message. 


Parameters: recipient — email address of recipient. 


attach(filename=None, content_type=None, data=None, disposition=None, headers=None) 
Adds an attachment to the message. 
Parameters: 


e filename — filename of attachment 

e content type — file mimetype 

e data — the raw file data 

e disposition — content-disposition (if any) 


Flask-PyMongo 


MongoDB 是 一 个 开源 的 数据 库 ， 它 存储 着 灵活 的 类 -JSON 的 “文档 ”"。 与 关系 数据 库 中 的 数据 
行 相反 ， 它 能 够 存储 任何 的 数字 ， 名 称 ， 或 者 复杂 的 层级 结构 。Python 开发 者 可 以 考虑 把 
MongoDB 作为 一 个 持久 化 ， 可 搜索 的 Python 字典 的 “仓库 "(实际 上 ， 这 是 如 何 用 PyMongo 
来 表示 MongoDB 中 的 “文档 ”)。 


Flask-PyMongo 架 起 来 Flask 和 PyMongo 之 间 的 桥梁 ， 因 此 你 能 够 使 用 Flask 正常 的 机 制 去 
配置 和 连接 MongoDB。 


REAN 
首先 ， 安 装 Flask-PyMongo: 


$ pip install Flask-PyMongo 


Flask-PyMongo 的 各 种 依赖 ， 比 如 ， 最 新 版 本 的 Flask (0.8 或 者 以 上 ) 以 及 PyMongo (2.4 
或 者 以 上 ) ， 也 会 为 你 安装 的 。Flask-PyMongo 是 兼容 Python 2.6, 2.7, 和 3.3 版 本 并 且 通 
过 测试 。 


接着 ， 在 你 的 代码 中 添加 一 个 PyMongo : 


from flask import Flask 
from flask.ext.pymongo import PyMongo 


app = Flask( name ) 
mongo - PyMongo(app) 


PyMongo 连接 运行 在 本 机 上 且 端 口 为 27017 的 MongoDB 服务 器 ， 并 且 假 设 默 认 的 数据 库 名 
A app.name ( 换 而 言 之 ， 你 可 以 使 用 传人 到 Flask 中 的 任何 数据 库 名 )。 这 个 数据 库 能 够 作 
为 db 属性 被 导入 。 


你 可 以 在 视图 中 直接 使 用 db : 


@app.route('/') 
def home_page(): 
online_users = mongo.db.users.find({'online': True}) 
return render template('index.html', 
online users-online users) 


Helpers 


Flask-PyMongo 提供 一 些 通 用 任务 的 现成 方法 : 


Collection.find one or 404(*args, **kwargs) 


Find and return a single document, or raise a 404 Not Found exception if no document 
matches the query spec. See find one() for details. 


@app.route('/user/<username>' ) 
def user profile(username): 
user = mongo.db.users.find one or 404([' id': username}) 
return render template('user.html', 
user-user) 





PyMongo.send file(filename, base='fs', version--1, cache for-31536000) 


Return an instance of the response class containing the named file, and implement 
conditional GET semantics (using make conditional() ). 


@app.route('/uploads/<path: filename>' ) 
def get_upload( filename): 
return mongo.send_file(filename) 


Parameters: 


e filename (sir) — the filename of the file to return 

e base (sír) — the base name of the GridFS collections to use 

e version (bool) — if positive, return the Nth revision of the file identified by filename; if 
negative, return the Nth most recent revision. If no such version exists, return with 
HTTP status 404. 

e cache for (in?) - number of seconds that browsers should be instructed to cache 
responses 


PyMongo.save file(filename, fileobj, base='fs', content type-None) 


Save the file-like object to GridFS using the given filename. Returns wone . 


@app.route('/uploads/<path:filename>', methods-['POST']) 
def save upload(filename): 
mongo.save file(filename, request.files['file']) 
return redirect(url for('get upload', filename-filename)) 


Parameters: 


e filename (sir) — the filename of the file to return 

e fileobj (file) — the file-like object to save 

e base (sír) — base the base name of the GridFS collections to use 

e content type (sir) — the MIME content-type of the file. If None , the content-type is 
guessed from the filename using guess type() 


class flask pymongo.BSONObjectIdConverter(map) 


A simple converter for the RESTful URL routing system of Flask. 


Qapp.route('/«ObjectId:task id»') 


def show task(task id): 


task - mongo.db.tasks.find one or 404(task id) 
return render template('task.html', task-task) 


Valid object ID strings are converted into objectid objects; invalid strings result in a 404 


error. The converter is automatically registered by the initialization of Py«ongo with keyword 


ObjectId . 


Configuration 


PyMongo 直接 支持 如 下 的 配置 项 : 


MONGO URI 


MONGO. HOST 


MONGO PORT 


MONGO AUTO START. REQUEST 


MONGO MAX POOL SIZE 


MONGO SOCKET TIMEOUT MS 


MONGO CONNECT TIMEOUT MS 


MONGO. DBNAME 


MONGO. USERNAME 


MONGO. PASSWORD 


MONGO. REPLICA SET 


MONGO READ PREFERENCE 


MONGO. DOCUMENT CLASS 


一 个 MongoDB 网 址 用 于 其 他 配置 项 。 
你 的 MongoDB 服务 器 的 主机 名 或 者 IP 地 址 。 默认 : "localh 
你 的 MongoDB 服务 器 的 端口 。 默 认 : 27017。 


为 了 禁用 PyMongo 2.2 的 “auto start request" 行为 ， 设置 成 
MongoClient )。 默认 : True o 


(AJ 3%): PyMongo 连接 池 中 保持 空闲 连接 的 最 大 数量 。 默认 : 


(可 选 ): ( 整 型 ) 在 超时 前 套 接 字 人 允许 一 个 发 送 或 者 接收 的 耗 时 ( 
值 。 


(可 选 ): ( 整 型 ) 在 超时 前 允许 一 个 连接 的 耗 时 (毫秒 )。 BRIA: Py 
可 用 于 作为 db 属性 的 数据 库 名 。 默 认 : app.name 。 

用 于 认证 的 用 户 名 。 默 认 : None. 

用 于 认证 的 密码 。 软 认 : None o 


设置 成 连接 的 备份 集 的 名 称 ; 这 必须 匹配 到 各 份 集 的 内 部 名 ， 
http://www.mongodb.org/display/DOCS/ReplicatSet+Commi 
isMaster 命令 ) 决 定 的 。 默 认 : None o 


决定 如 何 读 取 路 由 到 各 份 集 的 成 员 。 必须 是 定义 在 


pymongo.read preferences.ReadPreference 中 的 一 个 常量 或 者 


告诉 pymongo 返回 定制 的 对 象 而 不 是 默认 的 字典 ， 比如 bs 


dictio 


当 pyMongo 或 者 init app() 仅仅 只 有 一 个 参数 调用 的 时 候 (the Flask 实例 )， 会 假设 配置 值 
的 前 级 是 monco ; 能 够 用 config prefix 来 覆盖 这 个 前 级 。 


这 个 技术 能 够 用 于 连接 多 个 数据 库 或 者 数据 服务 器 : 


app = Flask( name ) 


# connect to MongoDB with the defaults 
mongo1 = PyMongo(app) 


# connect to another MongoDB database on the same host 
app.config['MONGO2 DBNAME'] - 'dbname two' 
mongo2 = PyMongo(app, config prefix-'MONGO2!') 


# connect to another MongoDB server altogether 
app.config['MONGOS3 HOST'] = 'another.host.example.com' 
app.config['MONGOS3 PORT'] = 27017 
app.config['MONGO3_DBNAME'] = 'dbname three' 

mongo3 = PyMongo(app, config prefix-'MONGO3!) 


tz aware : 


Flask-PyMongo 一 直 使 用 通用 时 区 的 datetime 对 象 。 这 是 因为 当 建 立 连 接 的 时 候 它 设置 
tz aware 参数 为 True o M MongoDB 返回 的 datetime 对 象 一 直 是 UTC, 


safe : 


Flask-PyMongo 默认 地 设置 成 “safe” 模式 ， 这 会 导致 save() , insert() , update() ,和 
remove() 在 返回 前 一 直 等 待 着 服务 器 的 应 答 。 你 可 以 在 调用 的 时 候 通 过 传人 safe=False 
数 到 任何 一 个 受 影响 的 方法 中 来 覆盖 它 。 


参 


z 


Flask-RESTful 


Flask-RESTful 是 一 个 Flask 扩展 ， 它 添加 了 快速 构建 REST APIs 的 支持 。 它 当然 也 是 一 个 
能 够 跟 你 现 有 的 ORM/ 库 协同 工作 的 轻 量 级 的 扩展 。Flask-RESTful 鼓励 以 最 小 设置 的 最 佳 实 


践 。 如 果 你 熟悉 Flask 的 话 ，Flask-RESTful 应 该 很 容易 上 手 。 
Ja J+ 
Ak 


使 用 pip 安装 Flask-RESTful: 


pip install flask-restful 


开发 的 版 本 可 以 从 GitHub 上 的 页 面 FR 


git clone https://github.com/twilio/flask-restful.git 
cd flask-restful 
python setup.py develop 


Flask-RESTful 有 如 下 的 依赖 包 ( 如 果 你 使 用 pip ， 依 赖 包 会 自动 地 安装 ): 
e Flask 版 本 0.8 或 者 更 高 


Flask-RESTful 要 求 Python 版 本 为 2.6, 2.7, 或 者 3.3。 


快速 入 门 


是 时 候 编写 你 第 一 个 REST API。 本 指南 假设 你 对 Flask 有 一 定 的 认识 ， 并 且 已 经 安装 了 
Flask 和 Flask-RESTful。 如 果 还 没有 安装 的 话 ， 可 以 依照 安装 章节 的 步骤 安装 。 


一 个 最 小 的 API 


一 个 最 小 的 Flask-RESTful API 像 这 样 : 


from flask import Flask 
from flask.ext import restful 


Flask( name ) 
restful.Api(app) 


app = 
api - 
class Helloworld(restful.Resource): 
def get(self): 
return {'hello': '‘world'} 


api.add resource(Helloworld, '/') 


if name == ' qain ': 
app.run(debug-True) 





把 上 述 代码 保存 为 api.py 并 且 在 你 的 Python 解释 器 中 运行 它 。 需 要 注意 地 是 我 们 已 经 启用 了 
Flask 调试 模式 ， 这 种 模式 提供 了 代码 的 重 载 以 及 更 好 的 错误 信息 。 调 试 模式 绝 不 能 在 生产 
环境 下 使 用 。 


$ python api.py 
* Running on http://127.0.0.1:5000/ 


现在 打开 一 个 新 的 命令 行 窗口 使 用 curd 测试 你 的 API: 


$ curl http://127.0.0.1:5000/ 
("hello": "world" 


资源 丰富 的 路 由 (Resourceful Routing) 


Flask-RESTful 提供 的 最 主要 的 基础 就 是 资源 (resources)。 资 源 (Resources) 是 构建 在 Flask 
可 拔 插 视图 之 上 ， 只 要 在 你 的 资源 (resource) 上 定义 方法 就 能 够 容易 地 访问 多 个 HTTP. 75 
法 。 一 个 待 办 事项 应 用 程序 的 基本 的 CRUD 资源 看 起 来 像 这 样 : 


from flask import Flask, request 
from flask.ext.restful import Resource, Api 


app = Flask( name ) 
api - Api(app) 
todos = {} 


class TodoSimple(Resource): 
def get(self, todo_id): 
return {todo_id: todos[todo_id]} 


def put(self, todo_id): 
todos[todo id] = request.form[ 'data' ] 
return {todo_id: todos[todo_id]} 


api.add resource(TodoSimple, '/«string:todo id»') 


if name == ' qain ': 
app.run(debug-True) 





你 可 以 尝试 这 样 : 


$ curl http://localhost:5000/todo1 -d "data-Remember the milk" -X PUT 
{"todoi": "Remember the milk") 

$ curl http://localhost:5000/todo1 

{"todoi": "Remember the milk") 

$ curl http://localhost:5000/todo2 -d "data=Change my brakepads" -X PUT 
{"todo2": "Change my brakepads"} 

$ curl http://localhost :5000/todo2 

{"todo2": "Change my brakepads"} 


或 者 如 果 你 安装 了 requests 库 的 话 ， 可 以 从 python shell 中 运行 : 


>>> from requests import put, get 

>>> put('http://localhost:5000/todo1', data={'data': 'Remember the milk'}).json() 
{u'todoi': u'Remember the milk'} 

>>> get('http://localhost:5000/todoi1').json() 

{u'todoi': u'Remember the milk'} 

>>> put('http://localhost:5000/todo2', data={'data': 'Change my brakepads'}).json() 
{u'todo2': u'Change my brakepads'} 

>>> get('http://localhost:5000/todo2').json() 

{u'todo2': u'Change my brakepads'} 


Flask-RESTful 支持 视图 方法 多 种 类 型 的 返回 值 。 同 Flask 一 样 ， 你 可 以 返回 任 一 迭代 器 ， 它 
将 会 被 转换 成 一 个 包含 原始 Flask 响应 对 象 的 响应 。Flask-RESTful 也 支持 使 用 多 个 返回 值 来 


设置 响应 代码 和 响应 头 ， 如 下 所 示 : 


class Todo1(Resource ) : 
def get(self): 
# Default to 200 OK 
return {'task': 'Hello world'} 


class Todo2(Resource): 
def get(self): 
# Set the response code to 201 
return {'task': 'Hello world'}, 201 


class Todo3(Resource): 
def get(self): 
# Set the response code to 201 and return custom headers 
return {'task': 'Hello world'}, 201, {'Etag': 'some-opaque-string'} 


lia (Endpoints) 


很 多 时 候 在 一 个 API 中 ， 你 的 资源 可 以 通过 多 个 URLs 访问 。 你 可 以 把 多 个 URLs 传 给 Api 
Xt RA) Api.add_resource() 方法 。 每 一 个 URL 都 能 访问 到 你 的 Resource 


api.add resource(HelloWworld, 
Va. 
' /hello') 


你 也 可 以 为 你 的 资源 方法 指定 endpoint 参数 。 


api.add resource(Todo, 
'/todo/«int:todo id>', endpoint-'todo ep') 


参数 解析 


尽管 Flask 能 够 简单 地 访问 请 求 数据 (比如 查询 字符 串 或 者 POST 表单 编码 的 数据 )， 验 证 表单 
数据 仍然 很 痛苦 。Flask-RESTful 内 置 了 支持 验证 请 求 数据 ， 它 使 用 了 一 个 类 似 argparse 的 
库 。 


S 


from flask.ext.restful import reqparse 
parser = regparse.RequestParser() 


parser.add argument('rate', type-int, help='Rate to charge for this resource!) 
args - parser.parse args() 


需要 注意 地 是 与 argparse 模块 不 同 ， reqparse.RequestParser.parse args() 返回 一 个 Python 
字典 而 不 是 一 个 自 定义 的 数据 结构 。 

使 用 reqparse 模块 同样 可 以 自由 地 提供 聪明 的 错误 信息 。 如 果 参 数 没 有 通过 验证 ，Flask- 
RESTful 将 会 以 一 个 400 错误 请 求 以 及 高 亮 的 错误 信息 回应 。 


$ curl -d 'rate-foo' http://127.0.0.1:5000/ 
('status': 400, 'message': 'foo cannot be converted to int'} 


inputs 模块 提供 了 许多 的 常见 的 转换 函数 ， 比如 inputs.date() 和 inputs.url() e 


使 用 strict=True 调用 parse args 能 够 确保 当 请 求 包 含 你 的 解析 器 中 未 定义 的 参数 的 时 候 
会 抛 出 一 个 异常 。 


args = parser.parse_args(strict=True) 


数据 格式 化 


默认 情况 下 ， 在 你 的 返回 迭代 中 所 有 字段 将 会 原样 星 现 。 尽 管 当 你 刚刚 处 理 Python 数据 结构 
的 时 候 ， 觉 得 这 是 一 个 伟大 的 工作 ， 但 是 当 实 际 处 理 它们 的 时 候 ， 会 觉得 十 分 泪 吕 和 枯燥 。 
为 了 解决 这 个 问题 ，Flask-RESTful 提供 了 fields 模块 和 marshal witn() 装饰 器 。 类 似 
Django ORM 和 WTForm， 你 可 以 使 用 fields 模块 来 在 你 的 响应 中 格式 化 结构 。 


from collections import OrderedDict 
from flask.ext.restful import fields, marshal with 


resource fields = { 
'task': fields.String, 
'uri': fields.Url('todo ep!) 
} 
class TodoDao(object): 
def | init (self, todo id, task): 


self.todo id - todo id 
self.task - task 


# This field will not be sent in the response 
self.status - 'active' 


class Todo(Resource): 
Qmarshal with(resource fields) 
def get(self, **kwargs): 
return TodoDao(todo id-'my todo', task-'Remember the milk') 


上 面 的 例子 接受 一 个 python 对 象 并 准备 将 其 序列 化 。 marshal_with() 装饰 器 将 会 应 用 到 由 
resource fields 描述 的 转换 。 从 对 象 中 提取 的 唯一 字段 是 tasko fields.url 域 是 一 个 特 
殊 的 域 ， 它 接受 端点 (endpoint) 名 称 作为 参数 并 且 在 响应 中 为 该 端点 生成 一 个 URL。 许 多 
你 需要 的 字段 类 型 都 已 经 包含 在 内 。 请 参阅 fields 指南 获取 一 个 完整 的 列表 。 


完整 的 例子 


在 api.py 中 保存 这 个 例子 


from flask import Flask 
from flask.ext.restful import reqparse, abort, Api, Resource 


app - Flask( name ) 

api = Api(app) 

TODOS - ( 
'todoi': {'task': 'build an API'}, 
'todo2': {'task': '?????'), 
'todo3': {'task': 'profit!'), 

} 


def abort if todo doesnt exist(todo id): 
if todo id not in TODOS: 
abort(404, message="Todo {} doesn't exist".format(todo id)) 





parser = regparse.RequestParser() 
parser.add argument('task', type=str) 


# Todo 
# show a single todo item and lets you delete them 
class Todo(Resource): 
def get(self, todo_id): 
abort_if_todo_doesnt_exist(todo_id) 
return TODOS[todo_id] 





def delete(self, todo_id): 
abort_if_todo_doesnt_exist(todo_id) 
del TODOS[todo_id] 
return '', 204 





def put(self, todo_id): 
args = parser.parse args() 
task = {'task': args['task']} 
TODOS[todo_id] = task 
return task, 201 


# TodoList 
# shows a list of all todos, and lets you POST to add new tasks 
class TodoList(Resource): 
def get(self): 
return TODOS 


def post(self): 
args = parser.parse_args() 
todo id = int(max(TODOS.keys()).1lstrip('todo')) + 1 
todo_id = 'todo%i' % todo_id 
TODOS[todo_id] = {'task': args['task']} 
return TODOS[todo_id], 201 


SH 

## Actually setup the Api resource routing here 
BH 

api.add resource(TodoList, '/todos') 

api.add resource(Todo, '/todos/«todo id»') 


if name == ' qain ': 
app.run(debug-True) 





用 法 示例 


$ python api.py 
* Running on http://127.0.0.1:5000/ 
* Restarting with reloader 


获取 列表 


$ curl http://localhost:5000/todos 
{"todoi": {"task": "build an API"}, "todo3": {"task": "profit!"}, "todo2": {"task": "???? 


mi = 
获取 一 个 单独 的 任务 








$ curl http://localhost :5000/todos/todo3 
{"task": "profit!"} 


删除 一 个 任务 


A 


curl http://localhost:5000/todos/todo2 -X DELETE -v 


DELETE /todos/todo2 HTTP/1.1 

User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.81 zlib 
Host: localhost :5000 

Accept: */* 


*VVVVV 


HTTP 1.0, assume close after body 
HTTP/1.0 204 NO CONTENT 
Content-Type: application/json 
Content-Length: 0 

Server: Werkzeug/0.8.3 Python/2.7.2 
Date: Mon, 01 Oct 2012 22:10:32 GMT 


| ———————————————Á »B——iw] 
增加 一 个 新 的 任务 


a INIEA 





$ curl http://localhost:5000/todos -d "task-something new" -X POST -v 


» POST /todos HTTP/1.1 

> User-Agent: curl/7.19.7 (universal-apple-darwini10.0) libcurl/7.19.7 OpenSSL/0.9.81 zlib 
» Host: localhost:5000 

» Accept: */* 

» Content-Length: 18 

» Content-Type: application/x-www-form-urlencoded 
> 

* HTTP 1.0, assume close after body 

< HTTP/1.0 201 CREATED 

< Content-Type: application/json 

< Content-Length: 25 

< Server: Werkzeug/0.8.3 Python/2.7.2 

< Date: Mon, 01 Oct 2012 22:12:58 GMT 

< 

* 


Closing connection #0 
{"task": "something new") 


EE] 
更 新 一 个 任务 





$ curl http://localhost:5000/todos/todo3 -d "task=something different" -X PUT -v 
» PUT /todos/todo3 HTTP/1.1 

» Host: localhost:5000 

» Accept: */* 

» Content-Length: 20 

» Content-Type: application/x-www-form-urlencoded 
> 

* HTTP 1.0, assume close after body 

« HTTP/1.0 201 CREATED 

« Content-Type: application/json 

« Content-Length: 27 

« Server: Werkzeug/0.8.3 Python/2.7.3 

« Date: Mon, 01 Oct 2012 22:13:00 GMT 

« 

* 


Closing connection #0 
{"task": "something different") 


请 求解 析 


Flask-RESTful 的 请 求解 析 接口 是 模仿 argparse 接口 。 它 设计 成 提供 简单 并 且 统一 的 访问 
Flask 中 flask.request 对 象 里 的 任何 变量 的 入 口 。 


基本 参数 


这 里 是 请 求解 析 一 个 简单 的 例子 。 它 寻 找 在 flask.Request.values 字典 里 的 两 个 参数 。 一 个 
类 型 为 int ， 另 一 个 的 类 型 是 str 


from flask.ext.restful import reqparse 


parser = regparse.RequestParser() 

parser.add argument('rate', type-int, help='Rate cannot be converted!) 
parser.add argument('name', type=str) 

args - parser.parse args() 


如 果 你 指定 了 help 参数 的 值 ， 在 解析 的 时 候 当 类 型 错误 被 触发 的 时 候 ， 它 将 会 被 作为 错误 信 
息 给 呈现 出 来 。 如 果 你 没有 指定 help 信息 的 话 ， 默 认 行 为 是 返回 类 型 错误 本 身 的 信息 。 


默认 下 ，arguments 不 是 必须 的 。 另外， 在 请 求 中 提供 的 参数 不 属于 RequestParser 的 一 部 
分 的 话 将 会 被 忽略 。 


另 请 注意 : 在 请 求解 析 中 声明 的 参数 如 果 没 有 在 请 求 本 身 设 置 的 话 将 默认 为 None o 


必需 的 参数 


要 求 





N 


个 值 传 递 的 参数 ， 只 需要 添加 required-True 来 调用 add argument() o 


parser.add argument('name', type=str, required-True, 
help="Name cannot be blank!") 


个 

多 个 值 & 列 表 

如 果 你 要 接受 一 个 键 有 多 个 值 的 话 ， 你 可 以 传 入 action='append' 
parser.add argument('name', type=str, action-'append') 

这 将 让 你 做 出 这 样 的 查询 
curl http://api.example.com -d "Name=bob" -d "Name=sue" -d "Name-joe" 


(REVS BUG ela 


args = parser.parse_args() 
args['name'] # ['bob', 'sue', 'joe'] 


其 它 目标 (Destinations) 


如 果 由 于 某 种 原因 ， 你 想 要 以 不 同 的 名 称 存储 你 的 参数 一 旦 它 被 解析 的 时 候 ， 你 可 以 使 用 


dest kwarg。 


parser.add_argument('name', type=str, dest='public_name' ) 


args = parser.parse_args() 
args['public name'] 


参数 位 置 


默认 下 ， RequestParser 试 着 从 flask.Request.values , 以 及 flask.Request.json 解析 值 。 


在 add argument( ) 中 使 用 location 参数 可 以 指定 解析 参数 的 位 置 。 flask.Request 中 任何 
变量 都 能 被 使 用 。 例 如 : 


# Look only in the POST body 
parser.add argument('name', type=int, location-'form') 


# Look only in the querystring 
parser.add argument('PageSize', type-int, location-'args') 


# From the request headers 
parser.add argument('User-Agent', type=str, location='headers' ) 


# From http cookies 
parser.add argument('session id', type=str, location='cookies' ) 


# From file uploads 
parser.add_argument('picture', type=werkzeug.datastructures.FileStorage, location='files' 


«| um | 








L 
多 个 位 置 
通过 传 入 一 个 列表 到 location 中 可 以 指定 多 个 参数 位 置 : 


parser.add argument('text', location-['headers', 'values']) 


列表 中 最 后 一 个 优先 出 现在 结果 集中 。 (例如 : location-['headers', values], fria 
‘values’ 的 结果 会 在 ‘headers’ 前 面 ) 


继承 解析 


往往 你 会 为 你 编写 的 每 个 资源 编写 不 同 的 解析 器 。 这 样 做 的 问题 就 是 如 果 解 析 器 具有 共同 的 
参数 。 不 是 重 写 ， 你 可 以 编写 一 个 包含 所 有 共享 参数 的 父 解 析 器 接着 使 用 copy() 扩充 它 。 

你 也 可 以 使 用 replace argument() 覆盖 父 级 的 任何 参数 ， 或 者 使 用 remove argument() 完全 
删除 参数 。 例如 : 


from flask.ext.restful import RequestParser 


parser - RequestParser() 
parser.add argument('foo', type-int) 


parser copy - parser.copy() 
parser copy.add argument('bar', type-int) 


4 parser copy has both 'foo' and 'bar' 
parser copy.replace argument('foo', type=str, required-True, location-'json') 
4 'foo' is now a required str located in json, not an int as defined 


# by original parser 


parser_copy.remove_argument('foo' ) 
# parser copy no longer has 'foo' argument 


输出 字段 


Flask-RESTful 提供 了 一 个 简单 的 方式 来 控制 在 你 的 响应 中 实际 呈现 什么 数据 。 使 用 fields 
模块 ， 你 可 以 使 用 在 你 的 资源 里 的 任意 对 象 (ORM 模型 、 定 制 的 类 等 等 ) HA fields 让 你 
格式 化 和 过 滤 响 应 ， 因 此 您 不 必 担 心 暴露 内 部 数据 结构 。 


当 查询 你 的 代码 的 时 候 ， 哪 些 数据 会 被 呈现 以 及 它们 如 何 被 格式 化 是 很 清楚 的 。 


基本 用 法 


你 可 以 定义 一 个 字典 或 者 fields 的 OrderedDict 类 型 ，OrderedDict 类 型 是 指 键 名 是 要 呈现 
的 对 象 的 属性 或 键 的 名 称 ， 键 值 是 一 个 类 ， 该 类 格式 化 和 返回 的 该 字段 的 值 。 这 个 例子 有 三 

个 字段 ， 两 个 是 字符 串 (Strings) 以 及 一 个 是 日 期 时 间 (DateTime) ， 格 式 为 RFC 822 日 

期 字符 串 〈 同 样 也 支持 ISO 8601) 


from flask.ext.restful import Resource, fields, marshal with 


resource fields = { 
'name': fields.String, 
'address': fields.String, 
'date updated': fields.DateTime(dt format-'rfc822'), 


} 
class Todo(Resource): 
Qmarshal with(resource fields, envelope='resource' ) 
def get(self, **kwargs): 
return db get todo() # Some function that queries the db 


这 个 例子 假设 你 有 一 个 自 定 义 的 数据 库 对 象 ( todo) ， 它 具有 属性 : name, address , 
以 及 date updated 。 该 对 象 上 任何 其 它 的 属性 可 以 被 认为 是 私有 的 不 会 在 输出 中 呈现 出 来 。 
一 个 可 选 的 envelope 关键 字 参 数 被 指定 为 封装 结果 输出 。 


装饰 器 marshal with 是 真正 接受 你 的 数据 对 象 并 且 过 滤 字 段 。 marshal with 能 够 在 单个 对 
象 ， 字 典 ， 或 者 列表 对 象 上 工作 。 


注意 : marshal with 是 一 个 很 便捷 的 装饰 器 ， 在 功能 上 等 效 于 如 下 的 
return marshal(db get todo(), resource fields), 200 。 这 个 明确 的 表达 式 能 用 于 返回 200 
以 及 其 它 的 HTTP 状态 码 作为 成 功 响应 〈 错 误 响 应 见 abort ) o 


重 命名 属性 


很 多 时 候 你 面向 公众 的 字段 名 称 是 不 同 于 内 部 的 属性 名 。 使 用 attribute 可 以 配置 这 种 映 
射 。 
fields = { 


'name': fields.String(attribute='private_name'), 
'address': fields.String, 


lambda 也 能 在 attribute 中 使 用 


fields = { 
'name': fields.String(attribute-lambda x: x. private name), 
'address': fields.String, 


默认 值 


如 果 由 于 某 种 原因 你 的 数据 对 象 中 并 没有 你 定义 的 字段 列表 中 的 属性 ， 你 可 以 指定 一 个 默认 
值 而 不 是 返回 None o 


fields = { 
'name': fields.String(default-'Anonymous User'), 
'address': fields.String, 


自 定义 字段 & 多 个 值 


有 时 候 你 有 你 自己 定义 格式 的 需求 。 你 可 以 继承 fields.Raw 类 并 且 实 现 格 式 化 函数 。 当 一 
个 属性 存储 多 条 信息 的 时 候 是 特别 有 用 的 。 例 如 ， 一 个 位 域 (bit-field) 各 位 代表 不 同 的 值 。 
你 可 以 使 用 fields 复 用 一 个 单一 的 属性 到 多 个 输出 值 (一 个 属性 在 不 同情 况 下 输出 不 同 的 
结果 ) 。 


这 个 例子 假设 在 flags 属性 的 第 一 位 标志 着 一 个 “正常 "或 者 “迫切 项， 第 二 位 标志 
着 “ 读 ” 与 “未 读 ”"。 这 些 项 可 能 很 容易 存储 在 一 个 位 字段 ， 但 是 可 读 性 不 高 。 转 换 它们 使 得 具有 
良好 的 可 读 性 是 很 容易 的 。 


class UrgentItem(fields.Raw): 
def format(self, value): 
return "Urgent" if value & 0x01 else "Normal" 


class UnreadItem(fields.Raw): 
def format(self, value): 
return "Unread" if value & 0x02 else "Read" 


fields = { 
'name': fields.String, 


'priority': UrgentItem(attribute='flags'), 
'status': UnreadItem(attribute-'flags'), 


Url & 其 它 具 体 字 段 


Flask-RESTful 包含 一 个 特别 的 字段 ， fields.url1 ， 即 为 所 请 求 的 资源 合成 一 个 uri。 这 也 是 
一 个 好 示例 ， 它 展示 了 如 何 添加 并 不 真正 在 你 的 数据 对 象 中 存在 的 数据 到 你 的 响应 中 。 


class RandomNumber (fields.Raw): 
def output(self, key, obj): 
return random.random( ) 


fields = { 
'name': fields.String, 
4 todo resource is the endpoint name when you called api.add resource() 
'uri': fields.Url('todo resource'), 
'random': RandomNumber, 


默认 情况 下 ， fields.uri 返回 一 个 相对 的 uri。 为 了 生成 包含 协议 (scheme) ， 主 机 名 以 及 
端口 的 绝对 uri， 需 要 在 字段 声明 的 时 候 传 人 absolute-True o fA scheme 关键 字 参 数 可 以 
履 盖 默认 的 协议 (scheme) : 


fields = { 
'uri': fields.Url('todo resource', absolute-True) 
'https uri': fields.Url('todo resource', absolute-True, scheme-'https') 


复杂 结构 
你 可 以 有 一 个 局 平 的 结构 ，marshal_with 将 会 把 它 转变 为 一 个 嵌 套 结构 


>>> from flask.ext.restful import fields, marshal 

>>> import json 

>>> 

>>> resource_fields = {'name': fields.String} 

>>> resource_fields['address'] = {} 

>>> resource fields['address']['line 1'] = fields.String(attribute='addr1' ) 
>>> resource fields['address']['line 2'] = fields.String(attribute='addr2' ) 
>>> resource_fields['address']['city'] = fields.String 

>>> resource_fields['address']['state'] = fields.String 

>>> resource_fields['address']['zip'] = fields.String 


>>> data = {'name': 'bob', 'addri': '123 fake street', 'addr2': '', 'city': 'New York', ' 
>>> json.dumps(marshal(data, resource fields)) 
(name "bob", "address": ("line 1": "123 fake street", "line 2": "", "state": "NY", "Z 


IL s —— Á— Z—— = 


注意 : address 字段 并 不 真正 地 存在 于 数据 对 象 中 ， 但 是 任何 一 个 子 字段 (sub-fields) 可 以 
直接 地 访问 对 象 的 属性 ， 就 像 没有 柑 套 一 样 。 





列表 字段 


你 也 可 以 把 字段 解 组 (unmarshal) 成 列表 


>>> from flask.ext.restful import fields, marshal 
>>> import json 


>>> 
>>> resource fields = {'name': fields.String, 'first names': fields.List(fields.String) } 
>>> data = {'name': 'Bougnazal', 'first_names' : ['Emile', 'Raoul']} 

>>> json.dumps(marshal(data, resource_fields) ) 

>>> '{"first_names": ["Emile", "Raoul"], "name": "Bougnazal"}' 
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Nested 解 组 (unmarshal) RERE a HEA EHEN Eio 


>>> from flask.ext.restful import fields, marshal 
>>> import json 


>>> address_fields = {} 

>>> address_fields['line 1'] fields.String(attribute-'addr1') 
>>> address fields['line 2'] fields.String(attribute-'addr2') 
>>> address fields['city'] = fields.String(attribute-'city') 
>>> address fields['state'] = fields.String(attribute-'state') 
>>> address fields['zip'] = fields.String(attribute='zip' ) 


>>> resource fields = {} 

>>> resource fields['name'] = fields.String 

>>> resource fields['billing address'] = fields.Nested(address fields) 

>>> resource fields['shipping address'] = fields.Nested(address fields) 

>>> addressi = {'addri': '123 fake street', 'city': 'New York', 'state': 'NY', 'zip': '10 
>>> address2 = {'addri': '555 nowhere', 'city': 'New York', 'state': 'NY', 'zip': '10468' 
>>> data = { 'name': 'bob', 'billing address': addressi, 'shipping address': address2} 
>>> 


>>> json.dumps(marshal with(data, resource fields)) 
'("billing address": ("line 1": "123 fake street", "line 2": null, "state": "NY", "zip": 


eel 


此 示例 使 用 两 个 府 套 字段 。 Nested MHiSMBIBFRNSRIEAFTSFE (sub-fields) 来 呈 
mo EH Nested 和 之 前 例子 中 的 伐 套 字典 之 间 的 重要 区 别 就 是 属性 的 上 下 文 。 在 本 例 中 
“biling_address” 是 一 个 具有 自己 字段 的 复 条 的 对 象 ， 传 递 给 伐 套 字段 的 上 下 文 是 子 对 象 
(sub-object) ， 而 不 是 原来 的 "数据 ?对象 。 换 句 话 说， data.billing_address.addr1 是 在 这 
里 的 范围 Gta: 这 里 是 直译 ) ， 然 而 在 之 前 例子 中 的 data.addr1 是 位 置 属性 。 记 住 : BR 
套 和 列表 对 象 创 建 一 个 新 属性 的 范围 。 





扩展 Flask-RESTful 


我 们 认识 到 每 一 个 人 在 REST 框架 上 有 着 不 同 的 需求 。Flask-RESTful 试图 尽 可 能 的 灵活 ， 但 
是 有 时 候 你 可 能 会 发 现 内 置 的 功能 不 足够 满足 你 的 需求 。Flask-RESTful 有 几 个 不 同 的 扩展 
点 ， 这 些 扩展 在 这 种 情况 下 会 有 帮助 。 


内 容 协商 


开 箱 即 用 ，Flask-RESTful 仅 配置 为 支持 JSON。 我 们 做 出 这 个 决定 是 为 了 给 API 维护 者 完全 
控制 API 格式 支持 ， 因 此 一 年 来 的 路 上 ， 你 不 必 支 持 那些 使 用 API AR CSV 表示 的 人 们 ， 
甚至 你 都 不 知道 他 们 的 存在 。 要 添加 其 它 的 mediatypes 到 你 的 API 中 ， 你 需要 在 api WR 
中 声明 你 支持 的 表示 。 


Flask( name ) 
restful.Api(app) 


app 
api 


Qapi.representation('application/json') 

def output json(data, code, headers=None): 
resp - make response(json.dumps(data), code) 
resp.headers.extend(headers or {}) 
return resp 


HERAT AWD EB Flask response 对 象 。 


AE FR & 输入 


一 种 最 常见 的 Flask-RESTful 附件 功能 就 是 基于 你 自己 数据 类 型 的 数据 来 定义 自 定义 的 类 型 
或 者 字段 。 


字段 


自 定 义 输 出 字段 让 你 无 需 直接 修改 内 部 对 象 执 行 自己 的 输出 格式 。 所 有 你 必须 做 的 就 是 继承 
Raw 并 且 实 现 format() 方法 : 


class AllCapsString(fields.Raw): 
def format(self, value): 
return value.upper() 


# example usage 
fields = { 


'name': fields.String, 
'all caps name': AllCapsString(attribute-name), 


输入 
对 于 解析 参数 ， 你 可 能 要 执行 自 定义 验证 。 创 建 你 自己 的 输入 类 型 让 你 轻松 地 扩展 请 求解 
析 。 


def odd number(value): 
if value % 2 == 0: 
raise ValueError("Value is not odd") 


return value 


请 求解 析 器 在 你 想 要 在 错误 消息 中 引用 名 称 的 情况 下 将 也 会 允许 你 访问 参数 的 名 称 。 


def odd number(value, name): 
if value % 2 == 0: 
raise ValueError("The parameter '{}' is not odd. You gave us the value: {}".forma 
return value 
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你 还 可 以 将 公开 的 参数 转换 为 内 部 表示 : 


maps the strings to their internal integer representation 
'init' => 0 

'in-progress' => 1 

'completed' -» 2 


dk dk dk dk 


def task status(value): 
statuses = [u"init", u"in-progress", u"completed"] 
return statuses. index(value) 


然后 你 可 以 在 你 的 RequestParser 中 使 用 这 些 自 定义 输入 类 型 : 


parser = regparse.RequestParser() 

parser.add argument('OddNumber', type-odd number) 
parser.add argument('Status', type-task status) 
args - parser.parse args() 


响应 格式 


为 了 支持 其 它 的 表示 ( 像 XML,CSV,HTML) ， 你 可 以 使 用 representation) 装饰 器 。 你 需 
要 在 你 的 API 中 引用 它 。 


api = restful.Api(app) 
Qapi.representation('text/csv') 
def output csv(data, code, headers=None): 


pass 
# implement csv output! 


这 些 输 出 函数 有 三 个 参数 ， data, code, LAM headers o 


data 是 你 从 你 的 资源 方法 返回 的 对 象 ， code 是 预计 的 HTTP TAA, headers 是 设置 在 
响应 中 任意 的 HTTP 头 。 你 的 输出 范 数 应 该 返回 一 个 Flask 响应 对 象 。 
def output json(data, code, headers=None): 
"""Makes a Flask response with a JSON encoded body""" 
resp = make_response(json.dumps(data), code) 


resp.headers.extend(headers or {}) 


return resp 


另外 一 种 实现 这 一 点 的 就 是 继承 Api 类 并 且 提 供 你 自己 输出 图 数 。 


class Api(restful.Api): 
def _ init (self, *args, **kwargs): 

super(Api, self). init (*args, **kwargs) 

self.representations = { 
‘application/xml': output xml, 
'text/html': output html, 
'text/csv': output csv, 
'application/json': output json, 


资源 方法 委 饰 器 


Resource() 有 一 个 叫做 method decorators 的 属性 。 你 可 以 继承 Resource 并 且 添 加 你 自己 
的 装饰 器 ， 该 装饰 器 将 会 被 添加 到 资源 里 面 所 有 method A, SHIR, MARNE AS 
一 个 请 求 建 立 自 定义 认证 。 
def authenticate(func): 
@wraps(func) 
def wrapper(*args, **kwargs): 


if not getattr(func, 'authenticated', True): 
return func(*args, **kwargs) 


acct = basic authentication() # custom account lookup function 


if acct: 
return func(*args, **kwargs) 


restful.abort(401) 
return wrapper 


class Resource(restful.Resource): 
method decorators - [authenticate] # applies to all inherited resources 


由 于 Flask-RESTful Resources 实际 上 是 Flask 视图 对 象 ， 你 也 可 以 使 用 标准 的 flask 视图 装 
饰 器 。 


自 定义 错误 处 理 器 


鞭 误 处 理 是 一 个 很 棘手 的 问题 。 你 的 Flask 应 用 可 能 身 兼 数 职 ， 然 而 你 要 以 正确 的 内 容 类 型 
以 及 错误 语法 义理 所 有 的 Flask-RESTful 错误 。 


Flask-RESTful 在 Flask-RESTful 路 由 上 发 生 任 何 一 个 400 或 者 500 错误 的 时 候 调 用 
handle error() 画 数 ， 不 会 干扰 到 其 它 的 路 由 。 你 可 能 需要 你 的 应 用 程序 在 404 Not Found 
错误 上 返回 一 个 携带 正确 媒体 类 型 (介质 类 型 ) 的 错误 信息 ; 在 这 种 情况 下 ， 使 用 api 构造 
RAHI catch all 4e4s 参数 。 


Flask( name ) 
flask restful.Api(app, catch all 404s-True) 


app 
api 


Flask-RESTful 会 义理 除了 自己 路 由 上 的 错误 还 有 应 用 程序 上 所 有 的 404 错误 。 


有 时 候 你 想 在 发 生 错 误 的 时 候 做 一 些 特别 的 东西 - 记录 到 文件 ， 发 送 邮件 ， 等 等 。 使 用 
got request exception() 方法 把 自 定 义 错 误 处 理 加 入 到 异常 。 


def log exception(sender, exception, **extra): 
""" Log an exception to our logging framework """ 
sender.logger.debug('Got exception during processing: %s', exception) 


from flask import got request exception 
got request exception.connect(log exception, app) 


定义 自 定 义 错 误 消 息 


在 一 个 请 求 期 间 遇 到 某 些 错误 的 时 候 ， 你 可 能 想 返 回 一 个 特定 的 消息 以 及 /或 者 状态 码 。 你 可 
以 告诉 Flask-RESTful 你 要 如 何 处 理 每 一 个 错误 /异常 ， 因 此 你 不 必 在 你 的 API 代码 中 编写 
try/except 代码 块 。 


errors = { 
'UserAlreadyExistsError': { 
'message': "A user with that username already exists.", 
'status': 409, 
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'ResourceDoesNotExist': { 
'message': "A resource with that ID no longer exists.", 
'status': 410, 
'extra': "Any extra information you want.", 


包含 'status' 键 可 以 设置 响应 的 状态 码 。 如 果 没 有 指定 的 话 ， 默 认 是 500. 
一 旦 你 的 errors 字典 定义 ， 简单 地 把 它 传 给 Api MS ER AX. 


app = Flask(__name_) 
api = flask_restful.Api(app, errors=errors) 


中 高 级 用 法 
本 页 涉及 构建 一 个 稍微 复杂 的 Flask-RESTful 应 用 程序 ， 该 应 用 程序 料 会 履 瘟 到 一 些 最 佳 练 


习 当 你 建立 一 个 真实 世界 的 基于 Flask-RESTful 的 API。 快 速 入 门 章节 适用 于 开始 你 的 第 一 
个 Flask-RESTful 应 用 程序 ， 因 此 如 果 你 是 Flask-RESTful 的 新 用 户 ， 最 好 查阅 该 章节 。 


项 目 结构 


有 许多 不 同 的 方式 来 组 织 你 的 Flask-RESTful 应 用 程序 ， 但 是 这 里 我 们 描述 了 一 个 在 大 型 的 
应 用 程序 中 能 够 很 好 地 扩展 并 且 维 持 一 个 不 错 的 文件 组 织 。 


最 基本 的 思路 就 是 把 你 的 应 用 程序 分 为 三 个 主要 部 分 。 路 由 ， 资 源 ， 以 及 任何 公共 的 基础 部 
分 。 


下 面 是 目录 结构 的 一 个 例子 : 


myapi/ 
C he oo 
app. py # this file contains your app and routes 
resources/ 
. init .py 
foo.py # contains logic for /Foo 
bar.py 4 contains logic for /Bar 
common/ 
. init .py 
util.py # just some common infrastructure 


common 文件 夹 可 能 只 包含 一 组 辅助 图 数 以 满足 你 的 应 用 程序 公共 的 需求 。 例 如 ， 它 也 可 能 
包含 任何 自 定义 输入 /输出 类 型 。 


在 resource 文件 夹 中 ， 你 只 有 资源 对 象 。 因 此 这 里 就 是 foo.py 可 能 的 样子 : 


from flask.ext import restful 


class Foo(restful.Resource): 
def get(self): 
pass 
def post(self): 
pass 


app.py 中 的 配置 就 像 这 样 : 


from flask import Flask 

from flask.ext import restful 

from myapi.resources.foo import Foo 
from myapi.resources.bar import Bar 
from myapi.resources.baz import Baz 


Flask( name ) 
restful.Api(app) 


app 
api 


api.add resource(Foo, '/Foo', '/Foo/«str:id»') 
api.add resource(Bar, '/Bar', '/Bar/<str:id>') 
api.add resource(Baz, '/Baz', '/Baz/<str:id>') 


因为 你 可 能 编写 一 个 特别 大 型 或 者 复杂 的 API， 这 个 文件 里 面 会 有 一 个 所 有 路 由 以 及 资源 的 复 
条 列表 。 你 也 可 以 使 用 这 个 文件 来 设置 任何 的 配置 值 (before request, after request) 。 基 
本 上 ， 这 个 文件 配置 你 整个 APl。 


完整 的 参数 解析 示例 


在 文档 的 其 它 地 方 ， 我 们 已 经 详细 地 介绍 了 如 何 使 用 reqparse 的 例子 。 这 里 我 们 将 设置 一 个 
有 多 个 输入 参数 的 资源 。 我 们 将 定义 一 个 名 为 “User 的 资源 。 


from flask.ext import restful 
from flask.ext.restful import fields, marshal with, reqparse 


def email(email str): 
""" return True if email str is a valid email """ 
if valid email(email): 
return True 
else: 
raise ValidationError("{} is not a valid email") 


post parser - regparse.RequestParser() 
post parser.add argument( 
'username', dest-'username', 
type-str, location='form', 
required-True, help='The user\'s username', 
) 
post parser.add argument( 
'email', dest='email', 
type-email, location='form', 
required-True, help='The user\'s email', 
) 
post parser.add argument( 
'user priority', dest-'user priority', 
type-int, location='form', 
default=1, choices=range(5), help='The user\'s priority', 


) 


user_fields = { 
'id': fields.Integer, 
'username': fields.String, 
'email': fields.String, 
'user priority': fields.Integer, 
'custom greeting': fields.FormattedString('Hey there {username}!'), 
'date created': fields.DateTime, 
'date updated': fields.DateTime, 
'links': fields.Nested({ 
'friends': fields.Url('/Users/{id}/Friends'), 
'posts': fields.Url('Users/{id}/Posts'), 
3), 
H 


class User(restful.Resource): 


Qmarshal with(user fields) 

def post(self): 
args - post parser.parse args() 
user - create user(args.username, args.email, args.user priority) 
return user 


Qmarshal with(user fields) 

def get(self, id): 
args - get parser.parse args() 
user - fetch user(id) 
return user 


正如 你 所 看 到 的 ， 我 们 创建 一 个 post_parser 专门 用 来 处 理解 析 POST 请 求 携带 的 参数 。 让 
我 们 逐步 介绍 每 一 个 定义 的 参数 。 


post parser.add argument( 
'username', dest-'username', 
type-str, location='form', 
required-True, help='The user\'s username', 


username 字段 是 所 有 参数 中 最 为 普通 的 。 它 从 POST 数据 中 获取 一 个 字符 串 并 且 把 它 转 换 
成 一 个 字符 串 类 型 。 该 参数 是 必须 得 ( required=True ) ， 这 就 意味 着 如 果 不 提 供 改 参数 ， 
Flask-RESTful 会 自动 地 返回 一 个 消息 是 ' 用 户 名 字段 是 必须 ' 的 400 错误 。 


post parser.add argument( 
'email', dest='email', 
type=email, location='form', 
required=True, help='The user\'s email', 


email 字段 是 一 个 自 定义 的 email 类型。 在 最 前 面 几 行 中 我 们 定义 了 一 个 email HH, € 
接受 一 个 字符 串 ， 如 果 该 字符 串 类 型 合法 的 话 返回 True， 否 则 会 引起 一 个 validationError 
异常 ， 该 异常 明确 表示 email 类 型 不 合法 。 


post parser.add argument( 
'user priority', dest-'user priority', 
type-int, location='form', 
default=1, choices-range(5), help='The user\'s priority', 


user_priority 类 型 充分 利用 了 choices 参数 。 这 就 意味 着 如 果 提 供 的 user priority 值 不 
落 在 由 choices 参数 指定 的 范围 内 的 话 ，Flask-RESTful 会 自动 地 以 400 状态 码 以 及 一 个 描 
述 性 的 错误 消息 响应 。 


下 面 该 讨论 到 输入 了 。 我 们 也 在 user_fields 字典 中 定义 了 一 些 有 趣 的 字段 类 型 用 来 展示 一 
些 特殊 的 类 型 。 


user fields = { 

'id': fields.Integer, 

'username': fields.String, 

'email': fields.String, 

'user priority': fields.Integer, 

'custom greeting': fields.FormattedString('Hey there {username}!'), 

'date created': fields.DateTime, 

'date updated': fields.DateTime, 

'links': fields.Nested({ 
'friends': fields.Url('/Users/{id}/Friends', absolute-True), 
'posts': fields.Url('Users/[id)/Posts', absolute-True), 

3) 


首先 ， 存在 一 个 fields.FormattedString o 


'custom greeting': fields.FormattedString('Hey there {username}!'), 


此 字段 主要 用 于 自 改 响应 中 的 值 到 其 它 的 值 。 在 这 种 情况 下 ， custom_greeting 将 总 是 包含 从 
username 字段 返回 的 值 。 


下 一 步 ， 检 查 fields.Nested 。 


'links': fields.Nested({ 
'friends': fields.Url('/Users/{id}/Friends', absolute=True), 
'posts': fields.Url('Users/[id)/Posts', absolute=True), 


I» 
此 字段 是 用 于 在 响应 中 创建 子 对 象 。 在 这 种 情况 下 ， 我 们 要 创建 一 个 包含 相关 对 象 urls 的 
links 子 对 象 。 注 意 这 里 我 们 是 使 用 了 fields.Nested o 


最 后 ， 我 们 使 用 了 fields.uri 字段 类 型 。 


'friends': fields.Url('/Users/{id}/Friends', absolute-True), 
'posts': fields.Url('Users/{id}/Posts', absolute-True), 


它 接受 一 个 字符 串 作为 参数 ， 它 能 以 我 们 上 面 提 到 的 fields.Formattedstring 同样 的 方式 被 


格式 化 。 传 人 absolute=true 确保 生成 的 Urls 包含 主机 名 。 


API 文档 


flask.ext.restful.marshal(data, fields, envelope=None) 


Takes raw data (in the form of a dict, list, object) and a dict of fields to output and filters the 
data based on those fields. 


Parameters: 


e data - the actual object(s) from which the fields are taken from 
e fields — a dict of whose keys will make up the final serialized response output 
e envelope — optional key that will be used to envelop the serialized response 


>>> from flask.ext.restful import fields, marshal 
>>> data = { 'a': 100, 'b': 'foo' } 
>>> mfields = { 'a': fields.Raw } 


>>> marshal(data, mfields) 
OrderedDict([('a', 100)]) 


>>> marshal(data, mfields, envelope='data' ) 
OrderedDict([('data', OrderedDict([('a', 100)]))]) 


flask.ext.restful.marshal with(fields, envelope=None) 


A decorator that apply marshalling to the return values of your methods. 


>>> from flask.ext.restful import fields, marshal with 
>>> mfields = { 'a': fields.Raw } 
>>> @marshal_with(mfields) 
. def get(): 
return ( 'a': 100, 'b': 'foo' } 


»»» get() 
OrderedDict([('a', 100)]) 


>>> (marshal with(mfields, envelope='data' ) 
. def get(): 
return ( 'a': 100, 'b': 'foo' } 


»»» get() 


OrderedDict([('data', OrderedDict([('a', 100)]))]) 


See flask.ext.restful.marshal() 


flask.ext.restful.marshal with field(field) 


A decorator that formats the return values of your methods with a single field. 


>>> from flask.ext.restful import marshal with field, fields 
>>> (Qmarshal with field(fields.List(fields.Integer)) 
. def get(): 
return ['1', 2, 3.0] 


»»» get() 
[1, 2, 3] 


See flask.ext.restful.marshal with() 


flask.ext.restful.abort(http status code, **kwargs) 


Raise a HTTPException for the given http status code. Attach any keyword arguments to 
the exception for later processing. 


Api 
class flask.ext.restful.Api(app=None, prefix-'', default mediatype-'application/json', dec 


The main entry point for the application. You need to initialize it with a Flask Application: 


>>> app 
>>> api 


Flask( name ) 
restful.Api(app) 


Alternatively, you can use init app() to set the Flask application after it has been 
constructed. 


Parameters: 


e app (flask.Flask) — the Flask application object 

e prefix (str) — Prefix all routes with a value, eg v1 or 2010-04-01 

e default mediatype (str) - The default media type to return 

e decorators (list) - Decorators to attach to every resource 

e catch all 404s (bool) - Use handie_error() to handle 404 errors throughout your app 

e url part order — A string that controls the order that the pieces of the url are 
concatenated when the full url is constructed. 'b' is the blueprint (or blueprint 
registration) prefix, 'a' is the api prefix, and 'e' is the path component the endpoint is 
added with 

e errors () — A dictionary to define a custom response for each exception or error raised 
during a request 


add resource(resource, *urls, **kwargs) 
Adds a resource to the api. 
Parameters: 


e resource ( nesource ) — the class name of your resource 

e urls (str) — one or more url routes to match for the resource, standard flask routing rules 
apply. Any url variables will be passed to the resource method as args. 

e endpoint (str) — endpoint name (defaults to Resource. name .lower() Can be used to 
reference this route in fields.Url fields 


Additional keyword arguments not specified above will be passed as-is to 
flask.Flask.add url rule() 


Examples: 


api.add resource(Helloworld, '/', '/hello') 
api.add resource(Foo, '/foo', endpoint="foo") 
api.add resource(FooSpecial, '/special/foo', endpoint="foo") 


error router(original handler, e) 


This function decides whether the error occured in a flask-restful endpoint or not. If it 
happened in a flask-restful endpoint, our handler will be dispatched. If it happened in an 
unrelated view, the app's original error handler will be dispatched. In the event that the error 
occurred in a flask-restful endpoint but the local handler can't resolve the situation, the router 
will fall back onto the original handler as last resort. 


Parameters: 


e original handler (function) — the original Flask error handler for the app 
e e (Exception) — the exception raised while handling the request 


handle error(e) 


Error handler for the API transforms a raised exception into a Flask response, with the 
appropriate HTTP status code and body. 


Parameters: e (Exception) — the raised Exception object 

init app(app) 

Initialize this class with the given flask.Flask application or flask.Blueprint object. 
Parameters: app (flask.Blueprint) — the Flask application or blueprint object 


Examples: 


api - Api() 
api.add resource(...) 
api.init app(app) 


make response(data, *args, **kwargs) 


Looks up the representation transformer for the requested media type, invoking the 
transformer to create a response object. This defaults to (application/json) if no transformer 
is found for the requested mediatype. 


Parameters: data — Python object containing response data to be transformed 
mediatypes() 


Returns a list of requested mediatypes sent in the Accept header 


mediatypes method() 
Return a method that returns a list of mediatypes 


output(resource) 


Wraps a resource (as a flask view function), for cases where the resource does not directly 
return a response object 


Parameters: resource — The resource as a flask view function 


owns endpoint(endpoint) 


Tests if an endpoint name (not path) belongs to this Api. Takes in to account the Blueprint 
name part of the endpoint name. 


Parameters: endpoint — The name of the endpoint being checked 


Returns: bool 


representation(mediatype) 


Allows additional representation transformers to be declared for the api. Transformers are 
functions that must be decorated with this method, passing the mediatype the transformer 
represents. Three arguments are passed to the transformer: 


e The data to be represented in the response body 
e The http status code 
e Adictionary of headers 


The transformer should convert the data appropriately for the mediatype and return a Flask 
response object. 


Ex: 


Qapi.representation('application/xml') 

def xml(data, code, headers): 
resp - make response(convert data to xml(data), code) 
resp.headers.extend(headers) 
return resp 


resource(*urls, **kwargs) 
Wraps a Resource class, adding it to the api. Parameters are the same as add resource() . 


Example: 


Flask( name ) 
restful.Api(app) 


app 
api 


Qapi.resource('/foo') 
class Foo(Resource): 
def get(self): 
return 'Hello, World!' 


unauthorized(response) 


Given a response, change it to ask for credentials 


url for(resource, **values) 


Generates a URL to the given resource. 


class flask.ext.restful.Resource 


Represents an abstract RESTful resource. Concrete resources should extend from this class 
and expose methods for each supported HTTP method. If a resource is invoked with an 
unsupported HTTP method, the API will return a response with status 405 Method Not 
Allowed. Otherwise the appropriate method is called and passed all arguments from the url 
rule used when adding the resource to an Api instance. See «add resource() for details. 


ReqParse 


class reqparse.RequestParser(argument class-«class 'reqparse.Argument'>, namespace class-« 


Enables adding and parsing of multiple arguments in the context of a single request. Ex: 


from flask import request 


parser - RequestParser() 

parser.add argument('foo') 

parser.add argument('int bar', type-int) 
args - parser.parse args() 


add argument(*args, **kwargs) 
Adds an argument to be parsed. 


Accepts either a single instance of Argument or arguments to be passed into Argument ‘s 
constructor. 


See Argument ‘s constructor for documentation on the available options. 
copy() 


Creates a copy of this RequestParser with the same set of arguments 


parse args(reqzNone, strict-False) 
Parse all arguments from the provided request and return the results as a Namespace 


Parameters: strict — if req includes args not in parser, throw 400 BadRequest exception 


remove argument (name) 


Remove the argument matching the given name. 


replace argument(name, *args, **kwargs) 


Replace the argument matching the given name with a new version. 


class reqparse.Argument(name, default-None, dest-None, required-False, ignore-False, type- 
Parameters: 


e name — Either a name or a list of option strings, e.g. foo or -f, -foo. 

e default — The value produced if the argument is absent from the request. 

e dest — The name of the attribute to be added to the object returned by parse args() . 

e required (bool) — Whether or not the argument may be omitted (optionals only). 

e action — The basic type of action to be taken when this argument is encountered in the 
request. Valid options are "store" and "append". 

e ignore — Whether to ignore cases where the argument fails type conversion 

e type — The type to which the request argument should be converted. If a type raises a 
ValidationError, the message in the error will be returned in the response. Defaults to 

unicode in python2 and str in python3. 


e location — The attributes of the flask.Request object to source the arguments from 
(ex: headers, args, etc.), can be an iterator. The last item listed takes precedence in the 
result set. 

e choices — A container of the allowable values for the argument. 

* help — A brief description of the argument, returned in the response when the argument 
is invalid with the name of the argument and the message passed to a ValidationError 
raised by a type converter. 

e case sensitive (bool) - Whether the arguments in the request are case sensitive or not 

e store missing (bool) — Whether the arguments default value should be stored if the 
argument is missing from the request. 


. init (name, default=None, dest=None, required-False, ignore-False, type-«function «lamb 


handle validation error(error) 


Called when an error is raised while parsing. Aborts the request with a 400 status and an 
error message 


Parameters: error — the error that was raised 
parse(request) 
Parses argument value(s) from the request, converting according to the argument's type. 


Parameters: request — The flask request object to parse arguments from 


source(request) 


Pulls values off the request in the provided location :param request: The flask request object 
to parse arguments from 


Fields 


class fields.String(default=None, attribute=None) 


Marshal a value as a string. Uses six.text type so values will be converted to unicode in 
python2 and str in pythons. 


format (value) 


class fields.Url(endpointzNone, absolute-False, scheme=None) 


FormattedString is used to interpolate other values from the response into this field. The 
syntax for the source string is the same as the string format method from the python stdlib. 


Ex: 


fields = { 
'name': fields.String, 
'greeting': fields.FormattedString("Hello {name}") 


} 
data = { 
'name': 'Doug', 


marshal(data, fields) 


output(key, obj) 

class fields.Url(endpoint=None, absolute=False, scheme=None) 
A string representation of a Url 

output(key, obj) 

class fields.DateTime(dt format-'rfc822', **kwargs) 


Return a formatted datetime string in UTC. Supported formats are RFC 822 and ISO 8601. 


Parameters: dt format (str) — 'rfc822' Or 'iso8601' 
format (value) 


class fields.Float(default=None, attribute=None) 


A double as IEEE-754 double precision. ex : 3.141592653589793 3.1415926535897933e- 
06 3.141592653589793e+24 nan inf -inf 


format (value) 
class fields.Integer(default-0, **kwargs) 
Field for outputting an integer value. 


Parameters: 


e default (int) — The default value for the field, if no value is specified. 
e attribute — If the public facing value differs from the internal value, use this to retrieve a 
different attribute from the response than the publicly named value. 


format (value) 
class fields.Arbitrary(default-None, attribute=None) 


A floating point number with an arbitrary precision 


ex: 634271127864378216478362784632784678324.23432 


format (value) 


class fields.Nested(nested, allow null-False, **kwargs) 


Allows you to nest one set of fields inside another. See 高 级 : REFE for more information 


Parameters: 


e nested (dict) — The dictionary to nest 
e allow null (boo/) — Whether to return None instead of a dictionary with null keys, if a 
nested dictionary has all-null keys 
e **kwargs — if default keyword argument is present, a nested dictionary will be 
marshaled as its value if nested dictionary is all-null keys (e.g. lets you return an empty 
JSON object instead of null) 
:keyword default 
output(key, obj) 
class fields.List(cls or instance, **kwargs) 
Field for marshalling lists of other fields. 


See 列表 字段 for more information. 


Parameters: cls or instance — The field type the list will contain. 
format (value) 
output(key, data) 


class fields.Raw(default-None, attribute-None) 


Raw provides a base field class from which others should extend. It applies no formatting by 
default, and should only be used in cases where data does not need to be formatted before 
being serialized. Fields should throw a MarshallingException in case of parsing problem. 


format (value) 


Formats a field's value. No-op by default - field classes that modify how the value of existing 
object keys should be presented should override this and apply the appropriate formatting. 


Parameters: value — The value to format 
Raises MarshallingException: 
In case of formatting problem 


Ex: 


class TitleCase(Raw): 
def format(self, value): 
return unicode(value).title() 


output(key, obj) 


Pulls the value forthe given key from the object, applies the fields formatting and returns the 
result. If the key is not found in the object, returns the default value. Field classes that create 
values which do not require the existence of the key in the object should override this and 
return the desired value. 


Raises MarshallingException: 


In case of formatting problem 


class fields.Boolean(default-None, attribute=None) 
Field for outputting a boolean value. 


Empty collections such as "" , {}, [] , etc. will be converted to False . 
format (value) 


class fields.Fixed(decimals-5, **kwargs) 


A decimal number with a fixed precision. 
format (value) 


fields.Price 


alias of Fixed 


Inputs 
flask.ext.restful.inputs.url(value) 
Validate a URL. 
Parameters: value (string) — The URL to validate 
Returns: The URL if valid. 


Raises: ValueError 
flask.ext.restful.inputs.regex 


flask.ext.restful.inputs.date(value) 


Parse a valid looking date in the format YYY Y-mm-dd 


flask.ext.restful.inputs.iso8601interval(value, argument='argument' ) 
Parses ISO 8601-formatted datetime intervals into tuples of datetimes. 


Accepts both a single date(time) or a full interval using either start/end or start/duration 
notation, with the following behavior: 


e Intervals are defined as inclusive start, exclusive end 


e Single datetimes are translated into the interval spanning the largest resolution not 
specified in the input value, up to the day. 

e The smallest accepted resolution is 1 second. 

e All timezones are accepted as values; returned datetimes are localized to UTC. Naive 
inputs and date inputs will are assumed UTC. 


Examples: 


"2013-01-01" -» datetime(2013, 1, 1), datetime(2013, 1, 2) 

"2013-01-01T12" -» datetime(2013, 1, 1, 12), datetime(2013, 1, 1, 13) 
"2013-01-01/2013-02-28" -» datetime(2013, 1, 1), datetime(2013, 2, 28) 

"2013-01-01/P3D" -» datetime(2013, 1, 1), datetime(2013, 1, 4) 

"2013-01-01T12:00/PT30M" -> datetime(2013, 1, 1, 12), datetime(2013, 1, 1, 12, 30) 
"2013-01-01T06:00/2013-01-01T12:00" -» datetime(2013, 1, 1, 6), datetime(2013, 1, 1, 12) 


Spo C e 
Parameters: value (str) — The |SO8601 date time as a string 

Returns: Two UTC datetimes, the start and the end of the specified interval 

Return type: A tuple (datetime, datetime) 


Raises: ValueError, if the interval is invalid. 


flask.ext.restful.inputs.natural(value, argument='argument' ) 


Restrict input type to the natural numbers (0, 1, 2, 3...) 


flask.ext.restful.inputs.boolean(value) 


Parse the string "true" or "false" as a boolean (case insensitive). Also accepts “1” and “0” as 
True/False (respectively). If the input is from the request JSON body, the type is already a 
native python boolean, and will be passed through without further parsing. 


flask.ext.restful.inputs.rfc822(dt) 
Turn a datetime object into a formatted date. 


Example: 


inputs.rfc822(datetime(2011, 1, 1)) => "Sat, 01 Jan 2011 00:00:00 -0000" 


Parameters: dt (datetime) — The datetime to transform 


Returns: A RFC 822 formatted date string 


运行 测试 


Makefile 文件 中 照顾 到 搭建 一 个 virtualenv 为 运行 测试 。 所 有 你 需要 做 的 就 是 运行 : 


$ make test 


要 更 改 用 于 运行 测试 的 Python 版 本 (默认 是 Python 2.7) ， 修 改 上 面 makefile 文件 中 的 


PYTHON MAJOR 和 PYTHON MINOR 变量 。 
你 可 以 在 所 有 支持 的 版 本 上 运行 测试 : 

$ make test-all 
单个 的 测试 可 以 使 用 如 下 格式 的 命令 运行 : 


nosetests «filename»:ClassName.func name 


例如 : 


$ source env/bin/activate 
$ nosetests tests/test reqgparse.py:ReqParseTestCase.test parse choices insensitive 


另外 ， 提 交 你 的 更 改 到 Github 中 你 的 分 支 上 ，Travis 将 会 自动 地 为 你 的 分 支 运行 测试 。 


也 提供 了 一 个 Tox 配置 文件 ， 因 此 你 可 以 在 本 地 在 多 个 python 版 本 (2.6，2.7，3.3， 和 
3.4) 上 测试 


$ tox 


使 用 Flask 设计 RESTful APls 


翻译 者 注 : 本 系列 的 原文 名 为 Designing a RESTful API with Python and Flask ， 作 者 是 
Miguel Grinberg 。 


使 用 Python 和 Flask 设计 RESTful API 


近 些 年 来 REST (REpresentational State Transfer) 已 经 变 成 了 web services 和 web APIs 的 
标 配 。 


在 本 文中 我 将 向 你 展示 如 何 简单 地 使 用 Python 和 Flask 框架 来 创建 一 个 RESTful 的 web 


Service。 


什么 是 REST ? 


六 条 设计 规范 定义 了 一 个 REST 系统 的 特点 : 


e 客户 端 -服务 器 : 客户 端 和 服务 器 之 间 隅 离 ， 服 务 器 提供 服务 ， 客 户 端 进行 消费 。 

。 DKA: 从 客户 端 到 服务 器 的 每 个 请 求 都 必须 包含 理解 请 求 所 必需 的 信息 。 换 句 话 说， AR 
务 器 不 会 存储 客户 端 上 一 次 请 求 的 信息 用 来 给 下 一 次 使 用 。 

e 可 缓存 : 服务 器 必须 明示 客户 端 请 求 能 否 缓存 。 

e 分 层 系统 : 客户 端 和 服务 器 之 间 的 通信 应该 以 一 种 标准 的 方式 ， 就 是 中 间 层 代替 服务 器 做 
出 响应 的 时 候 ， 客 户 端 不 需要 做 任何 变动 。 

e 统一 的 接口 : 服务 器 和 客户 端的 通信 方法 必须 是 统一 的 。 

e 按 需 编码 : 服务 器 可 以 提供 可 执行 代码 或 脚本 ， 为 客户 端 在 它们 的 环境 中 执行 。 这 个 约束 
是 唯一 一 个 是 可 选 的 。 


什么 是 一 个 RESTful 的 web service ? 


REST 架构 的 最 初 目的 是 适应 万 维 网 的 HTTP 协议 。 


RESTful web services 概念 的 核心 就 是 “资源 "。 资源 可 以 用 URI 来 表示 。 客 户 端 使 用 HTTP. 
协议 定义 的 方法 来 发 送 请 求 到 这 些 URIs， 当 然 可 能 会 导致 这 些 被 访问 的 "资源 “状态 的 改变 。 


HTTP 标准 的 方法 有 如 下 : 


GET 获取 资源 的 信息 http://example.com/api/orders 

GET 获取 某 个 特定 资源 的 信息 http://example.com/api/orders/123 
POST 创建 新 资源 http://example.com/api/orders 

PUT 更 新 资源 http://example.com/api/orders/123 
DELETE 删除 资源 http://example.com/api/orders/123 


REST 设计 不 需要 特定 的 数据 格式 。 在 请 求 中 数据 可 以 以 JSON 形式 , 或 者 有 时 候 作为 url 中 
查询 参数 项 。 


设计 一 个 简单 的 web service 


坚持 REST 的 准则 设计 一 个 web service 或 者 API 的 任务 就 变 成 一 个 标识 资源 被 展示 出 来 以 
及 它们 是 怎样 受 不 同 的 请 求 方 法 影响 的 练习 。 


比如 说 ， 我 们 要 编写 一 个 待 办 事项 应 用 程序 而 且 我 们 想 要 为 它 设 计 一 个 Web service。 要 做 的 
第 一 件 事情 就 是 决定 用 什么 样 的 根 URL 来 访问 该 服务 。 例 如 ， 我 们 可 以 通过 这 个 来 访问 : 


http://[hostname]/todo/api/v1.0/ 


在 这 里 我 已 经 决定 在 URL 中 包含 应 用 的 名 称 以 及 API 的 版 本 号 。 在 URL 中 包含 应 用 名 称 有 
助 于 提供 一 个 命名 空间 以 便 区 分 同一 系统 上 的 其 它 服务 。 在 URL 中 包含 版 本 号 能 够 帮助 以 后 
的 更 新 ， 如 果 新 版 本 中 存在 新 的 和 潜在 不 兼容 的 功能 ， 可 以 不 影响 依赖 于 较 旧 的 功能 的 应 用 

程序 。 


下 一 步骤 就 是 选择 将 由 该 服务 暴露 (展示 ) 的 资源 。 这 是 一 个 十 分 简单 地 应 用 ， 我 们 只 有 任务 ， 
因此 在 我 们 待 办 事项 中 唯一 的 资源 就 是 任务 。 


我 们 的 任务 资源 将 要 使 用 HTTP. 方法 如 下 : 


HTTP 方法 URL 动作 

GET http://[hostname]/todo/api/v1.0/tasks 检索 任务 列表 
GET http://[hostname]/todo/api/vi.0/tasks/[task id] 检索 某 个 任务 
POST http://[hostname]/todo/api/v1.0/tasks 创建 新 任务 
PUT http://[hostname]/todo/api/vi.O/tasks/[task id] 更 新 任务 
DELETE http://[hostname]/todo/api/v1.0/tasks/[task_id] 删除 任务 





我 们 定义 的 任务 有 如 下 一 些 属性 : 


。 id: 任务 的 唯一 标识 符 。 数 字 类 型 

e title: 简短 的 任务 描述 。 字 符 串 类 型 。 

e description: 具体 的 任务 描述 。 文 本 类 型 。 
e done: 任务 完成 的 状态 。 布 尔 值 。 


目前 为 止 关 于 我 们 的 web service 的 设计 基本 完成 。 剩 下 的 事情 就 是 实现 它 ! 


Flask 框架 的 简介 


如 果 你 读 过 Flask Mega-Tutorial 系列 ， 就 会 知道 Flask 是 一 个 简单 却 十 分 强大 的 Python web 
框架 。 


在 我 们 深入 研究 web services 的 细节 之 前 ， 让 我 们 回顾 一 下 一 个 普通 的 Flask Web 应 用 程序 
的 结构 。 


EEUU HAE Python 在 你 的 平台 上 工作 的 基本 知识 。 我 将 讲解 的 例子 是 工作 在 一 个 
X Unix 操作 系统 。 简 而 言 之 ， 这 意味 着 它们 能 工作 在 Linux，Mac OS X 和 Windows( 如 果 你 
ee. 如 果 你 使 用 Windows 上 原生 的 Python 版 本 的 话 ， 命 令 会 有 所 不 同 。 


让 我 们 开始 在 一 个 虚拟 环境 上 安装 Flask。 如 果 你 的 系统 上 没有 virtualenv， 你 可 以 从 
https://pypi.python.org/pypi/virtualenv 上 下 载 : 


$ mkdir todo-api 

$ cd todo-api 

$ virtualenv flask 

New python executable in flask/bin/python 

installing setúptools m EET done. 
MeO E p qu done. 

$ flask/bin/pip install flask 


既然 已 经 安装 了 Flask， 现 在 开始 创建 一 个 简单 地 网 页 应 用 ， 我 们 把 它 放 在 一 个 叫 app.py 的 
文件 中 : 


#!flask/bin/python 
from flask import Flask 


app = Flask( name ) 
@app.route('/') 
def index(): 

return "Hello, World!" 


if name == ' qain ': 
app.run(debug-True) 





为 了 运行 这 个 程序 我 们 必须 执行 app.py: 


$ chmod at+x app.py 


$ ./app.py 
* Running on http://127.0.0.1:5000/ 


* Restarting with reloader 


现在 你 可 以 启动 你 的 网 页 浏览 器 ， 输 入 http://localhost:5000 看 看 这 个 小 应 用 程序 的 效果 。 
简单 吧 ? 现在 我 们 将 这 个 应 用 程序 转换 成 我 们 的 RESTful service ! 


使 用 Python 和 Flask 实现 RESTful services 


使 用 Flask 构建 web services 是 十 分 简单 地 ， 比 我 在 Mega-Tutorial 中 构建 的 完整 的 服务 端 
的 应 用 程序 要 简单 地 多 。 


在 Flask 中 有 许多 扩展 来 帮助 我 们 构建 RESTful services， 但 是 在 我 看 来 这 个 任务 十 分 简单 ， 
没有 必要 使 用 Flask 扩展 。 


我 们 web service HE 户 端 需 要 添加 、 删 除 以 及 修改 任务 的 服务 ， 因 此 显然 我 们 需要 一 种 方式 
来 存储 任务 。 最 直接 的 方式 就 是 建立 一 个 小 型 的 数据 库 ， 但 是 数据 库 并 不 是 本 文 的 主体 。 学 
习 在 Flask 中 使 用 合适 的 数据 库 ， 我 强烈 建议 阅读 Mega-Tutorial。 


这 里 我 们 直接 把 任务 列表 存储 在 内 存 中 ， 因 此 这 些 任 务 列表 只 会 在 web 服务 器 运行 中 工作 ， 
在 结束 的 时 候 就 失效 。 这 种 方式 只 是 适用 我 们 自己 开发 的 web 服务 器 ， 不 适用 于 生产 环境 的 
web 服务 器 ， 这 种 情况 一 个 合适 的 数据 库 的 搭建 是 必须 的 。 
我 们 现在 来 实现 web service 的 第 一 个 入 口 : 
#!flask/bin/python 
from flask import Flask, jsonify 
app = Flask( name ) 
tasks - [ 
dao m ab. 
'title': u'Buy groceries', 


'description': u'Milk, Cheese, Pizza, Fruit, Tylenol', 
'done': False 


3 
t 
Ioe Zy 
'title': u'Learn Python', 
'description': u'Need to find a good Python tutorial on the web', 
'done': False 
} 


] 


Qapp.route('/todo/api/vi.0/tasks', methods=['GET']) 
def get_tasks(): 
return jsonify({'tasks': tasks}) 


if name == ' qain 
app.run(debug-True) 





正如 你 所 见 ， 没 有 多 大 的 变化 。 我 们 创建 一 个 任务 的 内 存 数据 库 ， 这 里 无 非 就 是 一 个 字典 和 
数组 。 数 组 中 的 每 一 个 元 素 都 具有 上 述 定义 的 任务 的 属性 。 


取代 了 首页 ， 我 们 现在 拥有 一 个 get tasks 的 函数 ， 访 问 的 URI 为 /todo/api/v1.0/tasks, 3f 
且 只 人 允许 GET BY HTTP 方法 。 


这 个 函数 的 响应 不 是 文本 ， 我 们 使 用 JSON 数据 格式 来 响应 ，Flask 的 jsonify 函数 从 我 们 的 
数据 结构 中 生成 。 


使 用 网 页 浏览 器 来 测试 我 们 的 web service 不 是 一 个 最 好 的 注意 ， 因 为 网 页 浏览 器 上 不 能 轻易 
地 模拟 所 有 的 HTTP 请 求 的 方法 。 相 反 ， 我 们 会 使 用 curl。 如 果 你 还 没有 安装 curl 的 话 ， 请 


立即 安装 它 。 
通过 执行 app.py， 启 动 web service。 接 着 打开 一 个 新 的 控制 台 窗 口 ， 运 行 以 下 命令 : 


$ curl -i http://localhost:5000/todo/api/v1.0/tasks 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 294 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 04:53:53 GMT 


"tasks": [ 
{ 
"description": "Milk, Cheese, Pizza, Fruit, Tylenol", 
"done": false, 
Datos “aly 
"title": "Buy groceries" 
3 
{ 
"description": "Need to find a good Python tutorial on the web", 
"done": false, 
Watlol Ree 
"title": "Learn Python" 
} 
] 


我 们 已 经 成 功 地 调用 我 们 的 RESTful service 的 一 个 函数 ! 


现在 我 们 开始 编写 GET 方法 请 求 我 们 的 任务 资源 的 第 二 个 版 本 。 这 是 一 个 用 来 返回 单独 一 个 
任务 的 函数 : 


from flask import abort 


@app.route('/todo/api/v1.0/tasks/<int:task_id>', methods=['GET']) 
def get_task(task_id): 
task = filter(lambda t: t['id'] == task_id, tasks) 
if len(task) == 0: 
abort(404) 
return jsonify({'task': task[0]}) 


第 二 个 函数 有 些 意思 。 这 里 我 们 得 到 了 URL 中 任务 的 id， 接着 Flask 把 它 转 换 成 BAH 
task_id 的 参数 。 


我 们 用 这 个 参数 来 搜索 我 们 的 任务 数组 。 如 果 我 们 的 数据 库 中 不 存在 搜索 的 id， 我 们 将 会 返 
回 一 个 类 似 404 的 错误 ， 根 据 HTTP 规范 的 意思 是 “资源 未 找到 ”。 


如 果 我 们 找到 相应 的 任务 ， 那 么 我 们 只 需 将 它 用 jsonify 打包 成 ISON 格式 并 将 其 发 送 作为 响 
应 ， 就 像 我 们 以 前 那样 处 理 整个 任务 集合 。 


调用 curl 请 求 的 结果 如 下 : 


$ curl -i http://localhost :5000/todo/api/v1.0/tasks/2 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 151 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 05:21:50 GMT 


"task": { 
"description": "Need to find a good Python tutorial on the web", 
"done": false, 
Dota 2, 
"title": "Learn Python" 
} 


} 
$ curl -i http://localhost :5000/todo/api/v1.0/tasks/3 


HTTP/1.0 404 NOT FOUND 
Content-Type: text/html 
Content-Length: 238 

Server: Werkzeug/0.8.3 Python/2.7.3 
Date: Mon, 20 May 2013 05:21:52 GMT 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 

<title>404 Not Found</title> 

<h1>Not Found</h1> 

<p>The requested URL was not found on the server.</p><p>If you entered the URL manual 


IE 


当 我 们 请 求 id #2 的 资源 时 候 ， 我 们 获取 到 了 ， 但 是 当 我 们 请 求 #3 的 时 候 返 回 了 404 错误 。 
有 关 错 误 奇 怪 的 是 返回 的 是 HTML 信息 而 不 是 JSON， 这 是 因为 Flask 按照 默认 方式 生成 
404 响应 。 由 于 这 是 一 个 Web service 客户 端 希望 我 们 总 是 以 JSON 格式 回应 ， 所 以 我 们 需 
要 改善 我 们 的 404 错误 处 理 程序 : 





from flask import make_response 


@app.errorhandler (404) 
def not_found(error): 
return make_response(jsonify({'error': 'Not found'}), 404) 


我 们 会 得 到 一 个 友好 的 错误 提示 : 


$ curl -i http://localhost :5000/todo/api/v1.0/tasks/3 
HTTP/1.0 404 NOT FOUND 

Content-Type: application/json 

Content-Length: 26 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 05:36:54 GMT 


"error": "Not found" 


} 


接 下 来 就 是 POST 方法 ， 我 们 用 来 在 我 们 的 任务 数据 库 中 插入 一 个 新 的 任务 : 


from flask import request 


@app.route('/todo/api/v1.0/tasks', methods=['POST']) 
def create_task(): 


if not request.json or not 'title' in request.json: 
abort(400) 

task = { 
'id': tasks[-1]['id'] + 1, 
'title': request.json['title'], 
'description': request.json.get('description', ""), 
'done': False 

} 

tasks.append(task) 

return jsonify({'task': task}), 201 


添加 一 个 新 的 任务 也 是 相当 容易 地 。 只 有 当 请 求 以 ISON 格式 形式 ，request.json 才 会 有 请 
求 的 数据 。 如 果 没 有 数据 ， 或 者 存在 数据 但 是 缺少 title 项 ， 我 们 将 会 返回 400， 这 是 表示 请 
求 无 效 。 


接着 我 们 会 创建 一 个 新 的 任务 字典 ， 使 用 最 后 一 个 任务 的 id + 1 作为 该 任务 的 id。 我 们 允许 
description 字段 缺失 ， 并 且 假 设 done 字段 设置 成 False。 


我 们 把 新 的 任务 添加 到 我 们 的 任务 数组 中 ， 并 且 把 新 添加 的 任务 和 状态 201 响应 给 客户 端 。 
使 用 如 下 的 curl 命 合 来 测试 这 个 新 的 函数 : 


$ curl -i -H "Content-Type: application/json" -X POST -d '{"title":"Read a book"}' http:/ 
HTTP/1.0 201 Created 


Content-Type: application/json 
Content-Length: 104 

Server: Werkzeug/0.8.3 Python/2.7.3 
Date: Mon, 20 May 2013 05:56:21 GMT 


"task": ( 
"description": "", 
"done": false, 
Wisi Ut 37 
"title": "Read a book" 





M Im 


注意 : 如 果 你 在 Windows 上 并 且 运 行 Cygwin 版 本 的 curl， 上 面 的 命令 不 会 有 任何 问题 。 然 
而 ， 如 果 你 使 用 原生 的 curl， 命 令 会 有 些 不 同 : 


curl -i -H "Content-Type: application/json" -X POST -d "("""title""":"""Read a book"""}" 


P E 





当然 在 完成 这 个 请 求 后 ， 我 们 可 以 得 到 任务 的 更 新 列表 : 


$ curl -i http://localhost:5000/todo/api/v1.0/tasks 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 423 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 05:57:44 GMT 


"tasks": [ 

{ 
"description": "Milk, Cheese, Pizza, Fruit, Tylenol", 
"done": false, 
vios al. 
"title": "Buy groceries" 

}, 

{ 
"description": "Need to find a good Python tutorial on the web", 
"done": false, 
i 
"title": "Learn Python" 

3 

t 
"description": "", 
"done": false, 
Joa ep 
"title": "Read a book" 

} 

] 
} 


剩 下 的 两 个 函数 如 下 所 示 : 


Qapp.route('/todo/api/vi.0/tasks/«int:task id»', methods=['PUT']) 
def update task(task id): 
task - filter(lambda t: t['id'] -- task id, tasks) 
if len(task) -- 0: 
abort(404) 
if not request.json: 
abort(400) 
if 'title' in request.json and type(request.json['title']) !- unicode: 
abort(400) 
if 'description' in request.json and type(request.json['description']) is not unicode 
abort(400) 
if 'done' in request.json and type(request.json['done']) is not bool: 
abort(400) 
task[O0]['title'] = request.json.get('title', task[0]['title']) 
task[0]['description'] = request.json.get('description', task[0]['description']) 
task[0]['done'] = request.json.get('done', task[0]['done']) 
return jsonify({'task': task[0]}) 


Qapp.route('/todo/api/vi.0/tasks/«int:task id»', methods-['DELETE']) 
def delete task(task id): 
task - filter(lambda t: t['id'] -- task id, tasks) 
if len(task) -- 0: 
abort(404) 
tasks.remove(task[0]) 
return jsonify({'result': True}) 


| 


delete task HARA A HIN. xt F update task 函数 ， 我 们 需要 严格 地 检查 输入 的 参数 
以 防止 可 能 的 问题 。 我 们 需要 确保 在 我 们 把 它 更 新 到 数据 库 之 前 ， 任 何 客户 端 提供 我 们 的 是 
预期 的 格式 。 


更 新 任务 #2 的 范 数 调用 如 下 所 示 : 


$ curl -i -H "Content-Type: application/json" -X PUT -d '{"done":true}' http://localhost: 
HTTP/1.0 200 OK 


Content-Type: application/json 
Content-Length: 170 

Server: Werkzeug/0.8.3 Python/2.7.3 
Date: Mon, 20 May 2013 07:10:16 GMT 


"task": [ 
t 
"description": "Need to find a good Python tutorial on the web", 
"done": true, 
"dg": 2» 
"title": "Learn Python" 
} 
] 





优化 web service 接口 


目前 API 的 设计 的 问题 就 是 迫 anced 党 在 任务 标识 返回 后 去 构造 URIs。 这 对 于 服务 器 是 十 分 


简单 的 ， 但 是 间接 地 人 迫使 客户 端 知道 这 些 URIs 是 如 何 构造 的 ， 这 将 会 阻碍 我 们 以 后 变更 这 些 
URIs. 


直接 返回 任务 的 ids， 我 们 直接 返回 控制 这 些 任务 的 完整 的 URI， 以 便 客 户 端 可 以 随时 使 用 
这 些 URIs。 为 此 ， 我 们 可 以 写 一 个 小 的 辅助 画 数 生成 一 个 “公共 ”版 本 任务 发 送 到 客户 端 


from flask import url for 


def make public task(task): 
new task = {} 
for field in task: 
if field -- 'id': 
new task['uri'] = url for('get task', task id-task['id'],  external-True) 
else: 
new task[field] - task[field] 
return new task 


pese NIMM ANM M peers 个 新 的 任务 ， 这 个 任务 的 id 字段 
被 替换 成 通过 Flask 的 url. for 生成 的 uri 字段 。 


当 我 们 返回 所 有 的 任务 列表 的 时 候 ， 在 发 送 到 客户 端 之 前 通过 这 个 图 数 进行 人 处理: 


Qapp.route('/todo/api/vi.0/tasks', methods-['GET']) 
def get tasks(): 


return jsonify({'tasks': map(make public task, tasks)}) 


里 就 是 客户 端 获取 任务 列表 的 时 候 得 到 的 数据 : 


$ curl -i http://localhost:5000/todo/api/v1.0/tasks 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 406 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 18:16:28 GMT 


"tasks": [ 


{ 
"title": "Buy groceries", 
"done": false, 
"description": "Milk, Cheese, Pizza, Fruit, Tylenol", 
"uri": "http://localhost:5000/todo/api/v1.0/tasks/1" 


"title": "Learn Python", 

"done": false, 

"description": "Need to find a good Python tutorial on the web", 
"uri": "http://localhost:5000/todo/api/v1.0/tasks/2" 


我 们 将 会 把 上 述 的 方式 应 用 到 其 它 所 有 的 函数 上 以 确保 客户 端 一 直 看 到 URIS 而 不 是 ids, 


加 强 RESTful web service 的 安全 性 


我 们 已 经 完成 了 我 们 web service 的 大 部 分 功能 ， 但 是 仍然 有 一 个 问题 。 我 们 的 web service 
对 任何 人 都 是 公开 的 ， 这 并 不 是 一 个 好 主意 。 


我 们 有 一 个 可 以 管理 我 们 的 待 办 事项 完整 的 web service， 但 在 当前 状态 下 的 web service 是 
开放 给 所 有 的 客户 端 。 如 果 一 个 陌生 人 弄 清 我 们 的 API 是 如 何 工 作 的 ， 他 或 她 可 以 编写 一 个 
客户 端 访问 我 们 的 web service 并 且 和 毁坏 我 们 的 数据 。 


大 部 分 初级 的 教程 会 忽略 这 个 问题 并 且 到 此 为 止 。 在 我 看 来 这 是 一 个 很 严重 的 问题 ， 我 必须 
指出 。 


确保 我 们 的 web service 安全 服务 的 最 简单 的 方法 是 要 求 客 户 端 提 供 一 个 用 户 名 和 密码 。 在 常 
规 的 web 应 用 程序 会 提供 一 个 登录 的 表单 用 来 认证 ， 并 且 服 务 器 会 创建 一 个 会 话 为 登录 的 用 
户 以 后 的 操作 使 用 ， 会 话 的 id 以 cookie 形式 存储 在 客户 端 浏览 器 中 。 然 而 REST 的 规则 之 
一 就 是 “无 状态 "， 因此 我 们 必须 要 求 客 户 端 在 每 一 次 请 求 中 提供 认证 的 信息 。 


我 们 一 直 试 着 尽 可 能 地 坚持 HTTP 标准 协议 。 既 然 我 们 需要 实现 认证 我 们 需要 在 HTTP 上 下 
文中 去 完成 ，HTTP 协议 提供 了 两 种 认证 机 制 : Basic 和 Digest。 


有 一 个 小 的 Flask 扩展 能 够 帮助 我 们 ， 我 们 可 以 先 安装 Flask-HTTPAuth: 


$ flask/bin/pip install flask-httpauth 


比方 说 ， 我 们 希望 我 们 的 web service 只 让 访问 用 户 名 miguel 和 密码 python 的 客户 端 访 问 。 


我 们 可 以 设置 一 个 基本 的 HTTP 验证 如 下 : 


from flask.ext.httpauth import HTTPBasicAuth 
auth - HTTPBasicAuth() 


Qauth.get password 
def get password(username): 
if username -- 'miguel': 
return 'python' 
return None 


Qauth.error handler 
def unauthorized(): 


return make response(jsonify(('error': 'Unauthorized access'}), 401) 


get password HR=e—TElwae A, Flask-HTTPAuth 使 用 它 来 获 
TESANKA, xTUNSUER E46 6 — T FH PIRE, ML AE an 


用 户 因 此 没有 必要 。 


给 定 用 户 的 密码 。 在 一 


error handler 回调 函数 是 用 于 给 客户 端 发 送 未 授权 错误 代码 。 像 我 们 处 理 其 它 的 错误 代码 ， 


这 里 我 们 定制 一 个 包含 JSON 数据 格式 而 不 是 HTML 的 响应 。 


随 着 认证 系统 的 建立 ， 所 剩 下 的 就 是 把 需要 认证 的 函数 添加 @auth.login_required 装 


例如 : 


Qapp.route('/todo/api/vi.0/tasks', methods=['GET']) 
Qauth.login required 
def get tasks(): 

return jsonify({'tasks': tasks}) 


如 果 现 在 要 尝试 使 用 curd 调用 这 个 函数 我 们 会 得 到 : 


$ curl -i http://localhost:5000/todo/api/v1.0/tasks 
HTTP/1.0 401 UNAUTHORIZED 

Content-Type: application/json 

Content-Length: 36 

WWW-Authenticate: Basic realm-"Authentication Required" 
Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 06:41:14 GMT 


"error": "Unauthorized access" 


AT BE45 18 FB xx NR 28 XB A E HE: 


$ curl -u miguel:python -i http://localhost:5000/todo/api/v1.0/tasks 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 316 

Server: Werkzeug/0.8.3 Python/2.7.3 

Date: Mon, 20 May 2013 06:46:45 GMT 


"tasks": [ 
{ 
"title": "Buy groceries", 
"done": false, 
"description": "Milk, Cheese, Pizza, Fruit, Tylenol", 
"uri": "http://localhost:5000/todo/api/v1.0/tasks/1" 
3 
t 
"title": "Learn Python", 
"done": false, 
"description": "Need to find a good Python tutorial on the web", 
"uri": "http://localhost:5000/todo/api/v1.0/tasks/2" 
} 
] 


认证 扩展 给 予 我 们 很 大 的 自由 选择 哪些 函数 需要 保护 ， 哪 些 函 数 需要 公开 。 


为 了 确保 登录 信息 的 安全 应 该 使 用 HTTP 安全 服务 器 (例如 : hitps://...)， 这 样 客户 端 和 服务 器 
之 间 的 通信 都 是 加 密 的 ， 以 防止 传输 过 程 中 第 三 方 看 到 认证 的 凭据 。 


让 人 不 舒服 的 是 当 请 求 收 到 一 个 401 的 错误 ， 网 页 浏览 都 会 跳出 一 个 圣 陋 的 登录 框 ， 即 使 请 
求 是 在 后 台 发 生 的 。 因 此 如 果 我 们 要 实现 一 个 完美 的 web 服务 器 的 话 ， 我 们 就 需要 禁止 跳 转 
到 浏览 器 显示 身份 验证 对 话 框 ， 让 我 们 的 客户 端 应 用 程序 自己 义理 登录 。 


一 个 简单 的 方式 就 是 不 返回 401 错误 。403 错误 是 一 个 合 人 青睐 的 替代 ，403 错误 表示 “ 禁 
止 ” 的 错误 : 


Qauth.error handler 
def unauthorized(): 
return make response(jsonify((['error': 'Unauthorized access'}), 403) 


可 能 的 改进 
我 们 编写 的 小 型 的 web service 还 可 以 在 不 少 的 方面 进行 改进 


对 于 初学 者 来 说 ， 一 个 真正 的 web service 需要 一 个 真实 的 数据 库 进 行 支 撑 。 我 们 现在 使 用 的 
内 存 数据 结构 会 有 很 多 限制 不 应 该 被 用 于 真正 的 应 用 。 


另外 一 个 可 以 提高 的 领域 就 是 处 理 多 用 户 。 如 果 系 统 支 持 多 用 户 的 话 ， 不 同 的 客户 端 可 以 发 
送 不 同 的 认证 凭证 获取 相应 用 户 的 任务 列表 。 在 这 样 一 个 系统 中 的 话 ， 我 们 需要 第 二 个 资源 
就 是 用 户 。 在 用 户 资源 上 的 POST 的 请 求 代表 注册 换 一 个 新 用 户 。 一 个 GET 请 求 表示 客户 端 
获取 一 个 用 户 的 信息 。 一 个 PUT 请 求 表示 更 新 用 户 信息 ， 比 如 可 能 是 更 新 邮箱 地 址 。 一 个 
DELETE 请 求 表 示 删 除 用 户 账 号 。 


GET 检索 任务 列表 请 求 可 以 在 几 个 方面 进行 扩展 。 首 先 可 以 携带 一 个 可 选 的 页 的 参数 ， 以 便 
客户 端 请 求 任务 的 一 部 分 。 另 外 ， 这 种 扩展 更 加 有 用 : 允许 按照 一 定 的 标准 筛选 。 比 如 ， 用 
户 只 想 要 看 到 完成 的 任务 ， 或 者 只 想 看 到 任务 的 标题 以 A 字 母 开 头 。 所 有 的 这 些 都 可 以 作为 
URL 的 一 个 参数 项 。 


使 用 Flask-RESTful 设计 RESTful API 


前 面 我 已 经 用 Flask 实现 了 一 个 RESTful 服务 器 。 今 天 我 们 将 会 使 用 Flask-RESTful 来 实现 
同一 个 RESTful 服务 器 ，Flask-RESTful 是 一 个 可 以 简化 APIs 的 构建 的 Flask 扩展 。 
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作为 一 个 提醒 ， 这 里 就 是 待 完成 事项 列表 web service 所 提供 的 方法 的 定义 : 


HTTP 方法 URL 动作 

GET http://[hostname]/todo/api/v1.0/tasks 检索 任务 列表 
GET http://[hostname]/todo/api/vi.0/tasks/[task id] 检索 某 个 任务 
POST http://[hostname]/todo/api/v1.0/tasks 创建 新 任务 
PUT http://[hostname]/todo/api/v1.0/tasks/[task_id] 更 新 任务 
DELETE http://[hostname]/todo/api/v1.0/tasks/[task_id] 删除 任务 


这 个 服务 唯一 的 资源 叫做 “任务 ”， 它 有 如 下 一 些 属性 : 





。 id: 任务 的 唯一 标识 符 。 数 字 类 型 。 

。 title: 简短 的 任务 描述 。 字 符 串 类 型 。 

。 description: 具体 的 任务 描述 。 文 本 类 型 。 
e done: 任务 完成 的 状态 。 布 尔 值 。 


路 由 


在 上 一 通 文 章 中 ， 我 使 用 了 Flask 的 视图 画 数 来 定义 所 有 的 路 由 。 


Flask-RESTful 提供 了 一 个 Resource 基础 类 ， 它 能 够 定义 一 个 给 定 URL 的 一 个 或 者 多 个 
HTTP 方法 。 例 如 ， 定 义 一 个 可 以 使 用 HTTP 的 GET PUT 以 及 DELETE 方法 的 User 资 
源 ， 你 的 代码 可 以 如 下 : 


from flask import Flask 
from flask.ext.restful import Api, Resource 


Flask( name ) 
Api(app) 


app 
api 


class UserAPI(Resource): 
def get(self, id): 
pass 


def put(self, id): 
pass 


def delete(self, id): 
pass 


api.add resource(UserAPI, '/users/<int:id>', endpoint = 'user') 


add resource PH 2 (FATS ZEB endpoint 注册 路 由 到 框架 上 。 如 果 没 有 指定 endpoint，Flask- 
RESTful 会 根据 类 名 生成 一 个 ， 但 是 有 时 候 有 些 画 数 比 如 url for 需要 endpoint， 因 此 我 会 明 
确 给 endpoint 赋值 。 


我 的 待 办 事项 API 定义 两 个 URLs : /todo/api/v1.0/tasks (获取 所 有 任务 列表 ) ， 以 及 
/todo/api/v1.0/tasks/ (获取 单个 任务 ) 。 我 们 现在 需要 两 个 资源 : 


class TaskListAPI(Resource): 
def get(self): 
pass 


def post(self): 
pass 


class TaskAPI(Resource): 
def get(self, id): 
pass 


def put(self, id): 
pass 


def delete(self, id): 
pass 


api.add resource(TaskListAPI, '/todo/api/vi.0/tasks', endpoint = 'tasks') 
api.add resource(TaskAPI, '/todo/api/v1.0/tasks/<int:id>', endpoint = 'task') 


解析 以 及 验证 请 求 


当 我 在 以 前 的 文章 中 实现 此 服务 器 的 时 候 ， 我 自己 对 请 求 的 数据 进行 验证 。 例 如 ， 在 之 前 版 
本 中 如 何 处 理 PUT 的 : 


Qapp.route('/todo/api/vi.0/tasks/«int:task id»', methods = ['PUT']) 
Qauth.login required 
def update task(task id): 
task - filter(lambda t: t['id'] -- task id, tasks) 
if len(task) -- 0: 
abort(404) 
if not request.json: 
abort(400) 
if 'title' in request.json and type(request.json['title']) !- unicode: 
abort(400) 
if 'description' in request.json and type(request.json['description']) is not unicode 
abort(400) 
if 'done' in request.json and type(request.json['done']) is not bool: 
abort(400) 
task[O0]['title'] = request.json.get('title', task[0]['title']) 
task[0]['description'] = request.json.get('description', task[0]['description']) 
task[0]['done'] = request.json.get('done', task[0]['done']) 
return jsonify( { 'task': make public task(task[0]) } ) 


HE 
在 这 里 , 我 必须 确保 请 求 中 给 出 的 数据 在 使 用 之 前 是 有 效 ， 这 样 使 得 函数 变 得 又 自 又 长 。 


Flask-RESTful 提供 了 一 个 更 好 的 方式 来 处 理 数据 验证 ， 它 叫做 RequestParser 类 。 这 个 
工作 方式 类 似 命令 行 解 析 工 具 argparse。 


» 


首先 ， 对 于 每 一 个 资源 需要 定义 参数 以 及 怎样 验证 它们 : 


from flask.ext.restful import reqparse 


class TaskListAPI(Resource): 
def | init (self): 
self.reqparse = reqparse.RequestParser() 
self.reqparse.add_argument('title', type = str, required = True, 
help = 'No task title provided', location = 'json') 
self.reqparse.add_argument('description', type = str, default = "", location = 'j 
super(TaskListAPI, self). init () 


Ho... 
class TaskAPI(Resource): 


def | init (self): 
self.reqparse = reqparse.RequestParser() 


self.reqparse.add argument('title', type = str, location = 'json') 
self.reqparse.add argument('description', type = str, location = 'json') 
self.reqparse.add_argument('done', type = bool, location = 'json') 


super(TaskAPI, self). init () 





ft TaskListAPI 资源 中 ，POST 方法 是 唯一 接收 参数 的 。 参 数 "标题 "是 必须 的 ， 因 此 我 定义 一 
个 缺少 "标题 "的 错误 信息 。 当 客户 端 缺少 这 个 参数 的 时 候 ，Flask-RESTful 将 会 把 这 个 错误 信 
息 作 为 响应 发 送 给 客户 端 。"“ 摘 述 ? 字 段 是 可 选 的 ， 当 缺少 这 个 字段 的 时 候 ， 黑 认 的 空 字符 串 将 
会 被 使 用 。 一 个 有 趣 的 方面 就 是 RequestParser 类 默认 情况 下 在 request.values HARE 
数 ， 因 此 location 可 选 参数 必须 被 设置 以 表明 请 求 过 来 的 参数 是 request.json 格式 的 。 


TaskAPI 资源 的 参数 义理 是 同样 的 方式 ， 但 是 有 少许 不 同 。PUT 方法 需要 解析 参数 ， 并 且 这 
个 方法 的 所 有 参数 都 是 可 选 的 。 


当 请 求解 析 器 被 初始 化 ， 解 析 和 验证 一 个 请 求 是 很 容易 的 。 例如 ， 请 注意 TaskAPl.put() 方法 
变 的 多 么 地 简单 : 
def put(self, id): 
task - filter(lambda t: t['id'] -- id, tasks) 
if len(task) -- 0: 
abort(404) 
task - task[0] 
args = self.regparse.parse args() 
for k, v in args.iteritems(): 
if v !- None: 
task[k] = v 
return jsonify( { 'task': make public task(task) } ) 


使 用 Flask-RESTful 来 处 理 验证 的 另 一 个 好 处 就 是 没有 必要 单独 地 处 理 类 似 HTTP. 400 $ 
3%, Flask-RESTful 会 来 处 理 这 些 。 


生成 响应 


原来 设计 的 REST 服务 器 使 用 Flask 的 jsonify 函数 来 生成 响应 。Flask-RESTful 会 自动 地 义 
理 转 换 成 JSON 数据 格式 ， 因 此 下 面 的 代码 需要 蔡 换 : 


return jsonify( { 'task': make_public task(task) } ) 


现在 需要 写成 这 样 : 


return ( 'task': make public task(task) ) 


Flask-RESTful 也 支持 自 定义 状态 码 ， 如 果 有 必要 的 话 : 


return { 'task': make public task(task) }, 201 


Flask-RESTful 还 有 更 多 的 功能 。make_public task 能 够 把 来 自 原始 服务 器 上 的 任务 从 内 部 
形式 包装 成 客户 端 想 要 的 外 部 形式 。 最 典型 的 就 是 把 任务 的 id 转 成 uri。Flask-RESTful 就 提 
供 一 个 辅助 函数 能 够 很 优雅 地 做 到 这 桩 的 转换 ， 不 仅仅 能 够 把 id 转 成 uri 并 且 能 够 转换 其 他 
的 参数 : 


from flask.ext.restful import fields, marshal 


task fields - ( 
'title': fields.String, 
'description': fields.String, 
'done': fields.Boolean, 
'uri': fields.Url('task') 

H 


class TaskAPI(Resource): 
Ho... 


def put(self, id): 
# 


return { 'task': marshal(task, task_fields) } 


task fields 结构 用 于 作为 marshal AMBER. fields.Uri 是 一 个 用 于 生成 一 个 URL 的 特定 的 
参数 。 它 需 要 的 参数 是 endpoint。 


认证 


在 REST 服务 器 中 的 路 由 都 是 由 HTTP 基本 身份 验证 保护 着 。 在 最 初 的 那个 服务 器 是 通过 使 
用 Flask-HTTPAuth 扩展 来 实现 的 。 


因为 Resouce 类 是 继承 自 Flask 的 MethodView， 它 能 够 通过 定义 decorators 变量 并 且 把 装 
饰 右 赋予 给 它 : 
from flask.ext.httpauth import HTTPBasicAuth 
Ho... 
auth - HTTPBasicAuth() 
Ho... 
class TaskAPI(Resource): 
decorators = [auth.login required] 
HV... 
class TaskAPI(Resource): 


decorators = [auth.login required] 
HS... 


使 用 Flask 设计 RESTful 的 认证 


今天 我 将 要 展示 一 个 简单 ， 不 过 很 安全 的 方式 用 来 保护 使 用 Flask 编写 的 API， 它 是 使 用 密码 
或 者 今 牌 认证 的 。 


示例 代码 


本 文 使 用 的 代码 能 够 在 github 上 找到 : REST-auth 。 


用 户 效 据 库 


为 了 让 给 出 的 示例 看 起 来 像 真 实 的 项 目 ， 这 里 我 将 使 用 Flask-SQLAlchemy 来 构建 用 户 数据 
库 模 型 并 且 存 储 到 数据 库 中 。 


用 户 的 数据 库 模 型 是 十 分 简单 的 。 对 于 每 一 个 用 户 ，username 和 password hash 将 会 被 存 
储 
class User(db.Model): 
__tablename__ = 'users' 
id = db.Column(db.Integer, primary_key = True) 


username = db.Column(db.String(32), index = True) 
password_hash = db.Column(db.String(128) ) 


出 于 安全 原因 ， 用 户 的 原始 密码 将 不 被 存储 ， 密 码 在 注册 时 被 散 列 后 存储 到 数据 库 中 。 使 用 
散 列 密码 的 话 ， 如 果 用 户 数据 库 不 小 心 落 入 恶意 攻击 者 的 手 里 ， 他 们 也 很 难 从 散 列 中 解析 到 
真实 的 密码 。 


密码 决 不 能 很 明确 地 存储 在 用 户 数据 库 中 。 


密码 散 列 
为 了 创建 密码 散 列 ， 我 将 会 使 用 PassLib 库 ， 一 个 专门 用 于 密码 散 列 的 Python €. 


PassLib 提供 了 多 种 散 列 算法 供 选择 。custom_app_context 是 一 个 易于 使 用 的 基于 
sha256 crypt 的 散 列 算法 。 


User 用 户 模型 需要 增加 两 个 新 方法 来 增加 密码 散 列 和 密码 验证 功能 : 


from passlib.apps import custom app context as pwd context 


class User(db.Model): 
Ho... 


def hash password(self, password): 
self.password hash - pwd context.encrypt(password) 


def verify password(self, password): 
return pwd context.verify(password, self.password hash) 


hash password() 函数 接受 一 个 明文 的 密码 作为 参数 并 且 存 储 明 文 密码 的 散 列 。 当 一 个 新 用 
户 注 册 到 服务 器 或 者 当 用 户 修改 密码 的 时 候 ， 这 个 函数 将 被 调用 。 


verify password() 函 数 接受 一 个 明文 的 密码 作为 参数 并 且 当 密码 正确 的 话 返回 True 或 者 密码 
鞋 误 的 话 返回 False。 这 个 画 数 当 用 户 提供 和 需要 验证 凭证 的 时 候 调 用 。 


你 可 能 会 问 如 果 原 始 密码 散 列 后 如 何 验证 原始 密码 的 ? 


散 列 算法 是 单 向 酚 数 ， 这 就 是 意味 着 它们 能 够 用 于 根据 密码 生成 散 列 ， 但 是 无 法 根据 生成 的 
散 列 逆向 猜测 出 原 密 码 。 然 而 这 些 算法 是 具有 确定 性 的 ， 给 定 相同 的 输入 它们 总 会 得 到 相同 
的 输出 。PassLib 所 有 需要 做 的 就 是 验证 密码 ， 通 过 使 用 注册 时 候 同一 个 函数 散 列 密码 并 且 同 
存储 在 数据 库 中 的 散 列 值 进行 比较 。 


用 户 注 册 


在 本 文 例子 中 ， 一 个 客户 端 可 以 使 用 POST 请 求 到 /api/users 上 注册 一 个 新 用 户 。 请 求 的 主 
体 必须 是 一 个 包含 username 和 password 的 JSON 格式 的 对 象 。 


Flask 中 的 路 由 的 实现 如 下 所 示 : 


Qapp.route('/api/users', methods = ['POST']) 
def new user(): 
username = request.json.get('username' ) 
password = request.json.get('password') 
if username is None or password is None: 
abort(400) # missing arguments 
if User.query.filter_by(username = username).first() is not None: 
abort(400) # existing user 
user = User(username = username) 
user .hash_password(password) 
db.session.add(user) 
db.session.commit() 
return jsonify({ 'username': user.username 3), 201, {'Location': url for('get user', 





RSRMEtAD Aib., BR username 和 password 是 从 请 求 中 携带 的 ISON 数据 中 获 
取 ， 接 着 验证 它们 。 


如 果 参 数 通过 验证 的 话 ， 新 的 User 实例 被 创建 。username 赋予 给 User， 接 着 使 用 
hash password 方法 散 列 密码 。 用 户 最 终 被 宇 入 数据 库 中 。 


响应 的 主体 是 一 个 表示 用 户 的 JSON 对 象 ，201 状态 码 以 及 一 个 指向 新 创建 的 用 户 的 URI 的 
HTTP 头 信 息 : Location。 


注意 : get user WAT EAE github 上 找到 完整 的 代码 。 


这 里 是 一 个 用 户 注 册 的 请 求 ， 发 送 自 curl: 


$ curl -i -X POST -H "Content-Type: application/json" -d '{"username":"miguel", "password" 
HTTP/1.0 201 CREATED 

Content-Type: application/json 

Content-Length: 27 

Location: http://127.0.0.1:5000/api/users/1 

Server: Werkzeug/0.9.4 Python/2.7.3 

Date: Thu, 28 Nov 2013 19:56:39 GMT 


"username": "miguel" 


} 
«| = 








需要 注意 地 是 在 真实 的 应 用 中 这 里 可 能 会 使 用 安全 的 的 HTTP (譬如 : HTTPS)。 如 果 用 户 登 
录 的 凭证 是 通过 明文 在 网 络 传输 的 话 ， 任 何 对 API 的 保 折 措施 是 毫 无 意义 的 。 


基于 密码 的 认证 


现在 我 们 假设 存在 一 个 资源 通过 一 个 API 暴露 给 那些 必须 注册 的 用 户 。 这 个 资源 是 通过 URL: 
/api/resource 能 够 访问 到 。 


为 了 保护 这 个 资源 ， 我 们 将 使 用 HTTP 基本 身份 认证 ， 但 是 不 是 自己 编写 完整 的 代码 来 实现 
它 ， 而 是 让 Flask-HTTPAuth 扩展 来 为 我 们 做 。 


使 用 Flask-HTTPAuth， 通 过 添加 login required 装饰 器 可 以 要 求 相 应 的 路 由 必须 进行 认证 : 


from flask.ext.httpauth import HTTPBasicAuth 
auth - HTTPBasicAuth() 


Qapp.route('/api/resource') 
Qauth.login required 
def get resource(): 
return jsonify({ 'data': 'Hello, %s!' % g.user.username }) 


但 是 ，Flask-HTTPAuth 需要 给 予 更 多 的 信息 来 验证 用 户 的 认证 ， 当 然 Flask-HTTPAuth 有 着 
许多 的 选项 ， 它 取决 于 应 用 程序 实现 的 安全 级 别 。 


能 够 提供 最 大 自由 度 的 选择 (可 能 这 也 是 唯一 兼容 PassLib 散 列 ) 就 是 选用 verify password E] 
调 画 数 ， 这 个 回调 男 数 将 会 根据 提供 的 username 和 password 的 组 合 的 ， 返 回 True( 通 过 验 
it) 或 者 Flase( 未 通过 验证 )。Flask-HTTPAuth 将 会 在 需要 验证 username 和 password 对 的 
时 候 调 用 这 个 回调 函数 。 


verify password 回调 函数 的 实现 如 下 : 


Qauth.verify password 
def verify password(username, password): 
user - User.query.filter by(username - username).first() 
if not user or not user.verify password(password): 
return False 
g.user - user 
return True 


PHASE username 找到 用 户 ， 并 且 使 用 verify password() 方法 验证 密码 。 如 果 认 
证 通过 的 话 ， 用 户 对 象 将 会 被 存储 在 Flask 的 g 对 象 中 ， 这 桩 视图 就 能 使 用 它 。 


这 里 是 用 curl 请 求 只 人 允许 注册 用 户 获取 的 保护 资 


$ curl -u miguel:python -i -X GET http://127.0.0.1:5000/api/resource 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 30 

Server: Werkzeug/0.9.4 Python/2.7.3 

Date: Thu, 28 Nov 2013 20:02:25 GMT 


"data": "Hello, miguel!" 


如 果 登 录 失 败 的 话 ， 会 得 到 下 面 的 内 容 : 


$ curl -u miguel:ruby -i -X GET http://127.0.0.1:5000/api/resource 
HTTP/1.0 401 UNAUTHORIZED 

Content-Type: text/html; charset=utf-8 

Content-Length: 19 

WWW-Authenticate: Basic realm="Authentication Required" 

Server: Werkzeug/0.9.4 Python/2.7.3 

Date: Thu, 28 Nov 2013 20:03:18 GMT 


Unauthorized Access 


这 里 我 再 次 重申 在 实际 的 应 用 中 ， 请 使 用 安全 的 HTTP。 


TIE 

每 次 请 求 必 须发 送 username 和 password 是 十 分 不 方便 ， 即 使 是 通过 安全 的 HTTP. 传输 的 
话 还 是 存在 风险 ， 因 为 客户 端 必 须要 存储 不 加 密 的 认证 赁 证， 这 样 才能 在 每 次 请 求 中 发 送 。 
一 种 基于 之 前 解决 方案 的 优化 就 是 使 用 今 牌 来 验证 请 求 。 


我 们 的 想法 是 客户 端 应 用 程序 使 用 认证 赁 证 交换 了 认证 今 牌 ， 接 下 来 的 请 求 只 发 送 认证 兮 
牌 。 


今 牌 是 具有 有 效 时 间 ， 过 了 有 效 时 间 后 ， 兮 牌 变 成 无 效 ， 需 要 重新 获取 新 的 邻 牌 。 今 牌 的 洪 
在 风险 在 于 生成 邻 牌 的 算法 比较 弱 ， 但 是 有 效 期 较 短 可 以 减少 风险 。 


有 很 多 的 方法 可 以 加 强 令 牌 。 一 个 简单 的 强化 方式 就 是 根据 存储 在 数据 库 中 的 用 户 以 及 密码 生 
成 一 个 随机 的 特定 长 度 的 字符 串 ， 可 能 过 期 日 期 也 在 里 面 。 今 牌 就 变 成 了 明文 密码 的 重 排 ， 
这 样 就 能 很 容易 地 进行 字符 串 对 比 ， 还 能 对 过 期 日 期 进行 检查 。 


更 加 完善 的 实现 就 是 不 需要 服务 器 端 进行 任何 存储 操作 ， 使 用 加 密 的 签名 作为 令 牌 。 这 种 方 
式 有 很 多 的 优点 ， 能 够 根据 用 户 信息 生成 相关 的 签名 ， 并 且 很 难 被 自 改 。 


Flask 使 用 类 似 的 方式 处 理 cookies 的 。 这 个 实现 依赖 于 一 个 叫做 itsdangerous 的 库 ， 我 们 这 
里 也 会 采用 它 。 


兮 牌 的 生成 以 及 验证 将 会 被 添加 到 User 模型 中 ， 其 具体 实现 如 下 : 


from itsdangerous import TimedJSONWebSignatureSerializer as Serializer 


class User(db.Model): 
HS... 


def generate auth token(self, expiration - 600): 
s = Serializer(app.config['SECRET KEY'], expires in = expiration) 
return s.dumps({ 'id': self.id }) 


@staticmethod 
def verify_auth_token(token): 
s = Serializer(app.config['SECRET KEY']) 
try: 
data = s.loads(token) 
except SignatureExpired: 
return None # valid token, but expired 
except BadSignature: 
return None # invalid token 
user - User.query.get(data['id']) 
return user 


generate auth token() 方法 生成 一 个 以 用 户 id 值 为 值 ，'id' 为 关键 字 的 字典 的 加 密 今 牌 。 兮 
牌 中 同时 加 入 了 一 个 过 期 时 间 ， 默 认为 十 分 钟 (600 秒 )。 


验证 倒 牌 是 在 verify auth token() 静态 方法 中 实现 的 。 静 态 方法 被 使 用 在 这 里 ， 是 因为 一 旦 
合 牌 被 解码 了 用 户 才 可 得 知 。 如 果 倒 牌 被 解码 了 ， 相 应 的 用 户 将 会 被 查询 出 来 并 且 返 回 。 


API 需要 一 个 获取 倒 牌 的 新 逆 数 ， 这 样 客户 端 才 能 申请 到 倒 牌 : 


@app.route('/api/token' ) 
Qauth.login required 
def get auth token(): 
token = g.user.generate auth token() 
return jsonify({ 'token': token.decode('ascii') }) 


注意 LG INZUEBHI T auth.login required 装饰 器 ， 也 就 是 说 需要 提供 username 和 
password。 


剩 下 来 的 就 是 决策 客户 端 怎样 在 请 求 中 包含 这 个 今 牌 。 


HTTP 基本 认证 方式 不 特别 要 求 usernames 和 passwords 用 于 认证 ， 在 HTTP 头 中 这 两 个 字 
段 可 以 用 于 任何 类 型 的 认证 信息 。 基 于 今 牌 的 认证 ， 兮 牌 可 以 作为 username 字段 ， 
password 字段 可 以 忽略 。 


这 就 意味 着 服务 器 需要 同时 义理 username 和 password 作为 认证 ， 以 及 兮 牌 作为 username 
的 认证 方式 。verify_password 回调 梢 数 需 要 同时 支持 这 两 种 方式 : 


Qauth.verify password 
def verify password(username or token, password): 
# first try to authenticate by token 
user - User.verify auth token(username or token) 
if not user: 
# try to authenticate with username/password 
user - User.query.filter by(username - username or token).first() 
if not user or not user.verify password(password): 
return False 
g.user - user 
return True 


Tue password ENERG TIENS 首先 它 会 把 username 参数 作为 今 牌 进行 
认证 。 如 果 没 有 验证 通过 的 话 ， 就 会 像 基 于 密码 认证 的 一 样 ， 验 证 Username 和 password。 


如 下 的 curl 请 求 能 够 获取 一 个 认证 的 使 牌 : 


$ curl -u miguel:python -i -X GET http://127.0.0.1:5000/api/token 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 139 

Server: Werkzeug/0.9.4 Python/2.7.3 

Date: Thu, 28 Nov 2013 20:04:15 GMT 


"token": "eyJhbGciOiJIUzIi1NilsImVACCIGMTMANTY2OTYA1NSwiaWFOI;joxMzg1Nj Y5MDU1fQ.eyJpZCI6MX 
} 


一 
现在 可 以 使 用 令 牌 获取 资源 : 





$ curl -u eyJhbGciOiJIUzI1NilsImVACcCIGMTMANTY2OTY1NSwiaWFOI joxMzgiNjY5MDUAfQ.eyJpZzCI6MXO. 
HTTP/1.0 200 OK 

Content-Type: application/json 

Content-Length: 30 

Server: Werkzeug/0.9.4 Python/2.7.3 

Date: Thu, 28 Nov 2013 20:05:08 GMT 


"data": "Hello, miguel!" 
[p ue (f£ 
需要 注意 的 是 这 里 并 没有 使 用 密码 。 





OAuth 认证 


当 我 们 讨论 RESTful 认证 的 时 候 ，OAuth 协议 经 常 被 提 及 到 。 
那么 什么 是 OAuth ? 


OAuth 可 以 有 很 多 的 含义 。 最 通常 就 是 一 个 应 用 程序 允许 其 它 应 用 程序 的 用 户 的 接 人 或 者 使 
用 服务 ， 但 是 用 户 必 须 使 用 应 用 程序 提供 的 登录 凭证 。 我 建议 阅读 者 可 以 浏览 OAuth 了 解 更 
多 知识 。 
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Flask-SQLAlchemy 


Flask-SQLAlchemy 是 一 个 为 您 的 Flask 应 用 增加 SQLAIchemy 支持 的 扩展 。 它 需 


SQLAlchemy 0.6 或 者 更 高 的 版 本 。 它 致力 于 简化 在 Flask 中 SQLAIchemy 的 使 用 ， 提 供 了 


有 用 的 默认 值 和 额外 的 助手 来 更 简单 地 完成 常见 任务 。 


快速 入 i 


Flask-SQLAIchemy 使 用 起 来 非常 有 趣 ， 对 于 基本 应 用 十 分 容易 使 用 ， 并 且 对 于 大 型 项 目 易 于 


扩展 。 有 关 完 整 的 指南 ， 请 参阅 soLAlchemy 的 API 文档 。 


一 个 最 小 应 用 


常见 情况 下 对 于 只 有 一 个 Flask 应 用 ， 所 有 您 需要 做 的 事情 就 是 创建 Flask 应 用 ， 


置 接着 创建 soLAlchemy 对 象 时 候 把 Flask 应 用 传递 给 它 作 为 参数 。 


选择 加 载 配 


一 旦 创建 ， 这 个 对 象 就 包含 sqlalchemy 和 sqlalchemy.orm OMAP RAAB. tbe 


提供 一 个 名 为 model 的 类 ， 用 于 作为 声明 模型 时 的 delarative x: 


from flask import Flask 
from flask.ext.sqlalchemy import SQLAlchemy 


app = Flask( name . 
app.config['SQLALCHEMY DATABASE URI'] = 'sqlite:////tmp/test.db' 
db - SQLAlchemy(app) 


class User(db.Model): 
id - db.Column(db.Integer, primary key-True) 
username - db.Column(db.String(80), unique-True) 
email - db.Column(db.String(120), unique-True) 


def | init (self, username, email): 
self.username - username 
self.email - email 


def repr (self): 
return '«User %r>' % self.username 


为 了 创建 初始 数据 库 ， 只 需要 从 交互 式 Python shell 中 导入 db 对 象 并 且 调 用 


SQLAlchemy.create all() 方法 来 创 建 表 和 数据 库 : 


>>> from yourapplication import db 
>>> db.create all() 


Boom, 您 的 数据 库 已 经 生成 。 现 在 来 创建 一 些 用 户 : 


>>> from yourapplication import User 
>>> admin = User('admin', 'adminQexample.com') 
>>> guest = User('guest', 'guest@example.com' ) 


但 是 它们 还 没有 真正 地 写 入 到 数据 库 中 ， 因 此 让 我 们 来 确保 它们 已 经 写 入 到 数据 库 中 : 


>>> db.session.add(admin) 
>>> db.session.add(guest) 
>>> db.session.commit() 


访问 数据 库 中 的 数据 也 是 十 分 简单 的 


>>> users = User.query.all() 

[xUser u'admin'>, «User u'guest'>] 

>>> admin = User.query.filter by(username-'admin').first() 
«User u'admin'» 


简单 的 关系 


SQLAlchemy 连接 到 关系 型 数据 库 ， 关 系 型 数据 最 擅长 的 东西 就 是 关系 。 因 此 ， 我 们 将 创建 
一 个 使 用 两 张 相 互 关联 的 表 的 应 用 作为 例子 : 


from datetime import datetime 


class Post(db.Model): 
id - db.Column(db.Integer, primary key-True) 
title - db.Column(db.String(80)) 
body - db.Column(db.Text) 
pub date - db.Column(db.DateTime) 


category id - db.Column(db.Integer, db.ForeignKey('category.id')) 
category - db.relationship('Category', 
backref=db.backref('posts', lazy='dynamic')) 


def _ init (self, title, body, category, pub_date=None): 
self.title = title 
self.body = body 
if pub_date is None: 
pub date = datetime.utcnow( ) 
self.pub_date = pub_date 
self.category = category 
def repr (self): 
return '«Post %r>' 96 self.title 


class Category(db.Model): 
id - db.Column(db.Integer, primary key-True) 
name - db.Column(db.String(50)) 


def _ init (self, name): 
self.name - name 


def _ repr (self): 
return '«Category %r>' % self.name 


首先 让 我 们 创建 一 些 对 象 : 


>>> py = Category('Python') 

>>> p = Post('Hello Python!', "Python is pretty cool', py) 
>>> db.session.add(py) 

>>> db.session.add(p) 


现在 因为 我 们 在 backref 中 声明 了 posts 作为 动态 关系 ， 查 询 显示 为 : 


>>> py.posts 
<sqlalchemy.orm.dynamic.AppenderBaseQuery object at 0x1027d37d0> 


它 的 行为 像 一 个 普通 的 查询 对 象 ， 因 此 我 们 可 以 查询 与 我 们 测试 的 “Python” 分 类 相关 的 所 有 
文章 (posts): 


>>> py.posts.all() 
[<Post 'Hello Python!'»] 


您 仅 需要 知道 与 普通 的 SQLAIchemy FAZA: 


1. sQLAlchemy 人 允许 您 访问 下 面 的 东西 : 
© sqlalchemy 和 sqlalchemy.orm 下 所 有 的 函数 和 类 
o 一 个 叫做 session 的 预 配置 范围 的 会 话 (session) 
metadata 属性 


o 


o engine 属性 
o SQLAlchemy.create all() 和 SQLAlchemy.drop all() ， 根据 模型 用 来 创建 以 及 删除 
表格 的 方法 


o 一 个 model 基 类 ， 即 是 一 个 已 配置 的 声明 (declarative) 的 基础 (base) 
2. Model 声明 基 类 行为 类 似 一 个 常规 的 Python 类 ， 不 过 有 个 query 属性 ， 可 以 用 来 查询 
模型 ( Model 和 BaseQuery ) 
3. 您 必须 提交 会 话 ， 但 是 没有 必要 在 每 个 请 求 后 删除 它 (session)，Flask-SQLAlchemy 会 帮 
您 完成 删除 操作 。 


引入 上 下 文 


如 果 您 计划 只 使 用 一 个 应 用 程序 ， 您 大 可 跳 过 这 一 章节 。 只 需要 把 您 的 应 用 程序 传 给 
SQLAlchemy 构造 男 数 ， 一 般 情 况 下 您 就 设置 好 了 。 然 而 您 想 要 使 用 不 止 一 个 点 用 或 者 在 一 个 
函数 中 动态 地 创建 应 用 的 话 ， 您 需要 仔细 阅读 。 


如 果 您 在 一 个 函数 中 定义 您 的 应 用 ， 但 是 saLAlchemy 对 象 是 全 局 的 ， 后 者 如 何 知 道 前 者 
了 ?答案 就 是 init app() RR: 


from flask import Flask 
from flask.ext.sqlalchemy import SQLAlchemy 


db = SQLAlchemy() 
def create app(): 
app = Flask( name ) 


db.init app(app) 
return app 


它 所 做 的 是 准备 应 用 以 与 soLAlchemy 共同 工作 。 然 而 现在 不 把 soLaAlchemy 对 象 绑 定 到 您 的 
应 用 。 为 什么 不 这 么 做 ? 因为 那里 可 能 创建 不 止 一 个 应 用 。 


那么 _sQLAlchemy 是 如 何 知道 您 的 应 用 的 ? 您 必须 配置 一 个 应 用 上 下 文 。 如 果 您 在 一 个 Flask 
视图 酌 数 中 进行 工作 ， 这 会 自动 实现 。 但 如 果 您 在 交互 式 的 shell 中 ， 您 需要 手动 这 么 做 。 
(参阅 创建 应 用 上 下 文 )。 


简 而 言 之 ， 像 这 样 做 : 


>>> from yourapp import create_app 
>>> app = create app() 
>>> app.app context().push() 


在 脚本 里 面 使 用 with FS BH HAVER: 


def my function(): 
with app.app context(): 
user - db.User(...) 
db.session.add(user) 
db.session.commit() 


Flask-SQLAlchemy 里 的 一 些 函 数 也 可 以 接受 要 在 其 上 进行 操作 的 应 用 作为 参数 : 


>>> from yourapp import db, create app 
>>> db.create_all(app=create_app()) 


Acie 
下 面 是 Flask-SQLAlchemy 中 存在 的 配置 值 。Flask-SQLAIchemy 从 您 的 Flask 主 配 置 中 加 载 


这 些 值 。 注意 其 中 的 一 些 在 引擎 创建 后 不 能 修改 ， 所 以 确保 尽早 配置 且 不 在 运行 时 修改 它 
们 。 


Ac i $e 


Flask-SQLAlchemy 扩展 能 够 识别 的 配置 键 的 清单 : 


SQLALCHEMY DATABASE URI 


SQLALCHEMY BINDS 


SQLALCHEMY ECHO 


SQLALCHEMY RECORD QUERIES 


SQLALCHEMY NATIVE UNICODE 


SQLALCHEMY POOL SIZE 


SQLALCHEMY POOL TIMEOUT 


SQLALCHEMY POOL RECYCLE 


SQLALCHEMY MAX OVERFLOW 


SQLALCHEMY TRACK MODIFICATIONS 


用 于 连接 数据 的 数据 库 。 例 如 : 
sglite:////tmp/test.db 
mysql://username: password@server/db 


一 个 映射 绑 定 (bind) 键 到 SQLAIchemy 连接 URIs 
的 字典 。 更 多 的 信息 请 参阅 绑 定 多 个 数据 库 。 


如 果 设 置 成 True, SQLAlchemy 将 会 记录 所 有 发 
到 标准 输出 (stderr) 的 语句 ， 这 对 调试 很 有 帮助 。 


可 以 用 于 显 式 地 禁用 或 者 启用 查询 记录 。 查 询 记 录 
在 调试 或 者 测试 模式 下 自动 和 启用。 更 多 信息 请 参阅 


get debug queries() 。 


可 以 用 于 显 式 地 禁用 支持 原生 的 unicode。 这 是 某 些 
数据 库 适 配器 必须 的 ( 像 在 Ubuntu 某 些 版 本 上 的 
PostgreSQL) ， 当 使 用 不 合适 的 指定 无 编码 的 数据 
E 默认 值 时 。 


数据 库 连 接 池 的 大 小 。 默 认 是 数据 库 引 擎 的 默认 值 
(通常 是 5) o 


指定 数据 库 连接 池 的 超时 时 间 。 默 认 是 10。 


自动 回收 连接 的 秒 数 。 这 对 MySQL 是 必须 的 ， 默 认 
情况 下 MySQL 会 自动 移 除 闲置 8 小 时 或 者 以 上 的 连 
接 。 需要 注意 地 是 如 果 使 用 MySQL 的 话 ， Flask- 
SQLAlchemy 会 自动 地 设置 这 个 值 为 2 小 时 。 


控制 在 连接 池 达 到 最 大 值 后 可 以 创建 的 连接 数 。 当 这 
些 额外 的 连接 回收 到 连接 池 后 将 会 被 断 开 和 抛弃 。 


如 果 设 置 成 True (默认 情况 )，Flask-SQLAIchemy 
将 会 追踪 对 象 的 修改 并 且 发 送信 号 。 这 需要 额外 的 内 
F, 如 果 不 必要 的 可 以 禁用 它 。 


New in version 0.8: 增加 SQLALCHEMY_NATIVE_UNICODE , SQLALCHEMY POOL SIZE , 


SQLALCHEMY POOL TIMEOUT 和 sQLALCHEMY POOL RECYCLE 配置 键 。 


New in version 0.12: 增加 soLALcHEMv BiNps 配置 键 。 


New in version 0.17: 增加 soLALcHEMY. MAX ovERFLOWw 配置 键 。 


New in version 2.0: 增加 soLALCHEMY TRACK MODIFICATIONS 配置 键 。 


连接 URI 格式 


完整 连接 URI 格式 列表 请 跳 转 到 SQLAlchemy 下 面 的 文档 (支持 的 数据 库 )。 这 里 展示 了 一 些 


常见 的 连接 字符 串 。 


SQLAlchemy 把 一 个 引擎 的 源 表 示 为 一 个 连同 设 定 引 警 选 项 的 可 选 字符 串 参 数 的 URI URI 


的 形式 是 : 


dialect+driver ://username: password@host: port/database 


该 字符 串 中 的 许多 部 分 是 可 选 的 。 如 果 没 有 指定 驱动 器 ， 会 选择 默认 的 (确保 在 这 种 情况 下 
不 包含 + ) 。 


Postgres: 


postgresql1://scott:tigerQlocalhost/mydatabase 


MySQL: 


mysql://scott:tiger@localhost/mydatabase 


Oracle: 


oracle://scott:tiger@127.0.0.1:1521/sidname 


SQLite (注意 开头 的 四 个 斜 线 ): 


sqlite:////absolute/path/to/foo.db 


使 用 目 定义 的 元 数据 和 命名 约定 


你 可 以 使 用 一 个 自 定义 的 metadata 对 象 来 构造 sQLAlchemy 对 象 。 这 人 允许 你 指定 一 个 BOE 
义 约束 命名 约定 。 这 样 做 对 数据 库 的 迁移 是 很 重要 的 。 因 为 SQL 没有 定义 一 个 标准 的 命名 约 
定 ， 无 法 保证 数据 库 之 间 实 现 是 兼容 的 。 你 可 以 自 定义 命名 约定 像 SQLAlchemy 文档 建议 那 


样 : 


from sqlalchemy import MetaData 
from flask import Flask 
from flask.ext.sqlalchemy import SQLAlchemy 


convention = { 


"ix": 
"ug" : 
"Ck": 
"fk: 
"pk": 


} 


metadata 


'ix 9?(column O label)s', 

"ug 9?((table name)s 9?((column O0 name)s", 
"ck_%(table_name)s_%(constraint_name)s", 
"fk_%(table_name)s_%(column_O_name)s_%(referred_table_name)s", 
"nk_%(table_name)s" 


MetaData(naming_convention=convention) 


db = SQLAlchemy(app, metadata=metadata) 


更 多 关于 MetaData 的 信息 ， 请 查看 官方 的 文档 。 


声明 模型 


通常 下 ，Flask-SQLAIchemy 的 行为 就 像 一 个 来 自 declarative 扩展 配置 正确 的 declarative 
基 类 。 因 此 ， 我 们 强烈 建议 您 阅读 SQLAlchemy 文档 以 获取 一 个 全 面 的 参考 。 尽 管 如 此 ， 我 
们 这 里 还 是 给 出 了 最 常用 的 示例 。 


需要 牢记 的 事情 : 


e 您 的 所 有 模型 的 基 类 叫做 db.Model 。 它 存储 在 您 必须 创建 的 SQLAIchemy 实例 上 。 细 
节 请 参阅 快速 入 门 。 

。 有 一 些 部 分 在 SQLAlchemy 上 是 必 选 的 ， 但 是 在 Flask-SQLAlchemy 上 是 可 选 的 。 比如 
表 名 是 自动 地 为 您 设置 好 的 ， 除 非 您 想 要 履 盖 它 。 它 是 从 转 成 小 写 的 类 名 派生 出 来 的 ， 


Bll “CamelCase” 444% 7j "camel case", 


简单 示例 
一 个 非常 简单 的 例子 : 


class User(db.Model): 
id - db.Column(db.Integer, primary key-True) 
username - db.Column(db.String(80), unique-True) 
email - db.Column(db.String(120), unique-True) 


def _ init (self, username, email): 


self.username - username 
self.email - email 


def repr (self): 
return '«User %r>' % self.username 


用 column 来 定义 一 列 。 列 名 就 是 您 赋值 给 那个 变量 的 名 称 。 如 果 您 想 要 在 表 中 使 用 不 同 的 
名 称 ， 您 可 以 提供 一 个 想 要 的 列 名 的 字符 串 作 为 可 选 第 一 个 参数 。 主 键 用 primary key-True 
标记 。 可 以 把 多 个 键 标记 为 主键 ， 此 时 它们 作为 复合 主键 。 


列 的 类 型 是 column 的 第 一 个 参数 。 您 可 以 直接 提供 它们 或 进一步 规定 〈 比 如 提供 一 个 长 
度 ) 。 下 面 的 类 型 是 最 常用 的 : 


Integer 一 个 整数 


string (Size) 有 长 度 限 制 的 字符 串 

Text 一 些 较 长 的 unicode 文本 

DateTime 表示 为 Python datetime 对 象 的 时 间 和 日 期 
Float 存储 浮 点 值 

Boolean 存储 布尔 值 

PickleType 存储 为 一 个 持久 化 的 Python 对 象 
LargeBinary 存储 一 个 任意 大 的 二 进 制 数据 


一 对 多 (one-to-many) 关 系 


最 为 常见 的 关系 就 是 一 对 多 的 关系 。 因 为 关系 在 它们 建立 之 前 就 已 经 声明 ， 您 可 以 使 用 字符 
串 来 指 代 还 没有 创建 的 类 (例如 如 果 Person 定义 了 一 个 到 Article 的 关系 ， 而 article 在 
文件 的 后 面 地 会 声明 )。 


关系 使 用 relationship() ERA ZR. 然而 外 键 必 须 用 类 sqlalchemy.schema.Foreignkey 来 单 
独 声明 : 


class Person(db.Model): 
id - db.Column(db.Integer, primary key-True) 
name = db.Column(db.String(50)) 
addresses = db.relationship('Address', backref='person', 
lazy='dynamic' ) 


class Address(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
email = db.Column(db.String(50)) 
person id = db.Column(db.Integer, db.ForeignKey('person.id')) 


db.relationship() 做 了 什么 ?这 个 函数 返回 一 个 可 以 做 许多 事情 的 新 属性 。 在 本 案例 中 ， 我 
们 让 它 指向 Address 类 并 加 载 多 个 地 址 。 它 如 何 知 道 会 返回 不 止 一 个 地 址 ? 因为 
SQLALchemy 从 您 的 声明 中 猜测 了 一 个 有 用 的 默认 值 。 如 果 您 想 要 一 对 一 关系 ， 您 可 以 把 


uselist-False 传 给 relationship() e 


那么 backref 和 lazy 意味 着 什么 了 ? backref 是 一 个 在 Address 类 上 声明 新 属性 的 简单 
方法 。 您 也 可 以 使 用 my address.person 来 获 甘 取 使 用 该 地 址 (address) 的 人 (person)。 lazy 
决定 了 SQLAlchemy 什么 时 候 从 数据 库 中 加 载 数据 : 


e 'select' (默认 值 ) 就 是 说 SQLAlchemy 会 使 用 一 个 标准 的 select 语句 必要 时 一 次 加 载 
数据 。 

e 'joined' 告诉 SQLAlchemy 使 用 Jorm 语句 作为 父 级 在 同一 查询 中 来 加 载 关系 。 

@  'subquery' 类 似 'joined' , 但 是 SQLAIchemy 会 使 用 子 查 询 。 


* ‘dynamic 在 有 多 条 数据 的 时 候 是 特别 有 用 的 。 不 是 直接 加 载 这 些 数据 ，SQLAIchemy 
会 返回 一 个 查询 对 象 ， 在 加 载 数据 前 您 可 以 过 滤 (提取 ) 它们 。 


您 如 何 为 反 向 引用 (backrefs) 定义 惰性 (lazy) 状态 ?使 用 backref() PHB: 


class User(db.Model): 
id - db.Column(db.Integer, primary key-True) 
name - db.Column(db.String(50)) 
addresses - db.relationship('Address', 
backref=db.backref('person', lazy='joined'), lazy-'dynamic') 


4 xt (many-to-many) K* 


如 果 您 想 要 用 多 对 多 关系 ， 您 需要 定义 一 个 用 于 关系 的 辅助 表 。 对 于 这 个 辅助 表 ， 强烈 建议 
不 使 用 模型 ， 而 是 采用 一 个 实际 的 表 : 


tags = db.Table('tags', 
db.Column('tag id', db.Integer, db.ForeignKey('tag.id')), 
db.Column('page id', db.Integer, db.ForeignKey('page.id')) 
) 
class Page(db.Model): 
id - db.Column(db.Integer, primary key-True) 
tags - db.relationship('Tag', secondary-tags, 
backref=db.backref('pages', lazy='dynamic')) 


class Tag(db.Model): 
id = db.Column(db.Integer, primary_key=True) 


这 里 我 们 配置 Page.tags 加 载 后 作为 标签 的 列表 ， 因 为 我 们 并 不 期 望 每 页 出 现 太 多 的 标签 。 
而 每 个 tag 的 页 面 列表 ( Tag.pages ) 是 一 个 动态 的 反 向 引用 。 正如 上 面 提 到 的 ， 这 意味 着 
您 会 得 到 一 个 可 以 发 起 select 的 查询 对 象 。 


选择 (Select), 插 入 (Insert), 删除 (Delete) 


现在 您 已 经 有 了 declared models， 是 时 候 从 数据 库 中 查询 数据 。 我 们 将 会 使 用 快速 入 门 章 
节 中 定义 的 数据 模型 。 


插入 记录 


在 查询 数据 之 前 我 们 必须 先 插入 数据 。 您 的 所 有 模型 都 应 该 有 一 个 构造 函数 ， 如 果 您 忘记 
了 ， 请 确保 加 上 一 个 。 只 有 您 自己 使 用 这 些 构 造 琅 数 而 SQLAIchemy 在 内 部 不 会 使 用 它 ， 所 
以 如 何 定 义 这 些 构造 画 数 完全 取决 与 您 。 


向 数据 库 插 入 数据 分 为 三 个 步骤 : 
1. @) Python 对 象 


2. 把 Ci AN aN Jn 到 会 


. 提交 会 话 


这 里 的 会 话 不 是 Flask 的 会 话 ， 而 是 Flask-SQLAIchemy 的 会 话 。 它 本 质 上 是 一 个 数据 库 事 
务 的 加 强 版 本 。 它 是 这 样 工作 的 : 


>>> from yourapp import User 

>>> me = User('admin', 'admin@example.com' ) 
>>> db.session.add(me) 

>>> db.session.commit() 


好 吧 ， 这 不 是 很 难 吧 。 但 是 在 您 把 对 象 添加 到 会 话 之 前 ， SQLAlchemy 基本 不 考虑 把 它 加 到 
事务 中 。 这 是 好 事 ， 因 为 您 仍然 可 以 放弃 更 改 。 上 比如 想象 在 一 个 页 面 上 创建 文章 ， 但 是 您 只 
想 把 文章 传递 给 模板 来 预览 泻 染 ， 而 不 是 把 它 存 进 数据 库 。 


调用 add() 画 数 会 添加 对 象 。 它 会 发 出 一 个 inser’ 语句 给 数据 库 ， 但 是 由 于 事务 仍然 没 
提交 ， 您 不 会 立即 得 到 返回 的 ID 。 如 果 您 提交 ， 您 的 用 户 会 有 一 个 ID: 


>>> me.id 
1 


删除 记录 
删除 记录 是 十 分 类 似 的 ， 使 用 delete) 代替 add() : 


>>> db.session.delete(me) 
>>> db.session.commit() 


查询 记录 


那么 我 们 怎么 从 数据 库 中 查询 数据 ? 为 此 ，Flask-SQLAIchemy 在 您 的 model 类 上 提供 了 
query 属性 。 当 您 访问 它 时 ， 您 会 得 到 一 个 新 的 所 有 记录 的 查询 对 象 。 在 使 用 ani) 或 者 
first() 发 起 查询 之 前 可 以 使 用 方法 filter() 来 过 滤 记 录 。 如 果 您 想 要 用 主键 查询 的 话 ， 
也 可 以 使 用 get() 。 


下 面 的 查询 假设 数据 库 中 有 如 下 条 目 : 


id username email 
1 admin admin@example.com 
2 peter peter@example.org 
3 guest guest@example.com 


通过 用 户 名 查询 用 户 : 


>>> peter = User.query.filter by(username-'peter').first() 
>>> peter.id 

1 

>>> peter.email 

u'peterQexample.org' 


同上 但 是 查询 一 个 不 存在 的 用 户 名 返回 None : 


>>> missing = User.query.filter_by(username='missing').first() 
>>> missing is None 
True 


使 用 更 复杂 的 表达 式 查 询 一 些 用 户 : 


>>> User.query.filter(User.email.endswith('Qexample.com')).all() 
[<User u'admin'>, «User u'guest'>] 


按 某 种 规则 对 用 户 排序 : 


>>> User.query.order by(User.username) 
[<User u'admin'», «User u'guest'», «User u'peter'>] 


限制 返回 用 户 的 数量 : 


>>> User.query.limit(1).all() 
[<User u'admin'»] 


用 主键 查询 用 户 : 


>>> User.query.get(1) 
«User u'admin'> 


在 视图 中 查询 


当 您 编写 Flask 视图 画 数 ， 对 于 不 存在 的 条 目 返 回 一 个 404 错误 是 非常 方便 的 。 因 为 这 是 一 
个 很 常见 的 问题 ，Flask-SQLAIchemy 为 了 解决 这 个 问题 提供 了 一 个 帮助 函数 。 可 以 使 用 
get or 404() 来 代替 get() ， 使 用 first_or_aoa() 来 代替 first() 。 这 样 会 抛 出 一 个 
404 错误 ， 而 不 是 返回 none : 


@app.route('/user/<username>' ) 

def show_user(username): 
user = User.query.filter by(username-username).first or 404() 
return render template('show user.html', user-user) 


绑 定 多 个 数据 库 


从 0.12 开始 ，Flask-SQLAIchemy 可 以 容易 地 连接 到 多 个 数据 库 。 为 了 实现 这 个 功能 ， 预 配 
iB f SQLAlchemy 来 支持 多 个 “binds”。 


什么 是 绑 定 (binds)? 在 SQLAlchemy 中 一 个 绑 定 (bind) 是 能 执行 SQL 语句 并 且 通 常 是 一 个 连 
接 或 者 引擎 类 的 东 东 。 在 Flask-SQLAIchemy 中 ， 绑 定 (bind) 总 是 背后 自动 为 您 创建 好 的 引 
擎 。 这 些 引 擎 中 的 每 个 之 后 都 会 关联 一 个 短 键 (bind key) 。 这 个 键 会 在 模型 声明 时 使 用 来 把 
一 个 模型 关联 到 一 个 特定 引擎 。 


如 果 模 型 没有 关联 一 个 特定 的 引擎 的 话 ， 就 会 使 用 默认 的 连接 ( soLALCHEMY DATABASE URI 配置 
值 )。 


示例 配置 


下 面 的 配置 声明 了 三 个 数据 库 连 接 。 特 殊 的 默认 值 和 另外 两 个 分 别名 为 users (用 于 用 户 ) 
和 appmeta 连接 到 一 个 提供 只 读 访 问 应 用 内 部 数据 的 sqlite 数据 库 ) : 


SQLALCHEMY DATABASE URI = 'postgres://localhost/main' 
SQLALCHEMY BINDS = { 
'users': 'mysqldb://localhost/users', 
'appmeta': "sqlite:////path/to/appmeta.db' 


创建 和 删除 表 


create all() 和 drop all() 方法 默认 作用 于 所 有 声明 的 绑 定 (bind)， 包括 默认 的 。 这 个 行 
为 可 以 通过 提供 bina 参数 来 定制 。 它 可 以 是 单个 绑 定 (bind) 名 ，' au c 指向 所 有 绑 定 
(binds) 或 一 个 绑 定 (bind) 名 的 列表 。 黑 认 的 绑 定 (bind)( SQLALCHEMY_DATABASE_URI ) 4 None : 


>>> db.create all() 

>>> db.create all(bind-['users']) 
>>> db.create all(bind-'appmeta') 
>>> db.drop_all(bind=None) 


ro . 
5| 4 (Binds) 
当 您 声明 模型 时 ， 您 可 以 用 — bina key ”属性 指定 绑 定 (bind): 


class User(db.Model): 
. bind key = 'users' 
id - db.Column(db.Integer, primary key-True) 
username - db.Column(db.String(80), unique-True) 


bind key 存储 在 表 中 的 info 字典 中 作为 'bind_key， 键 值 。 了 解 这 个 很 重要 ， 因 为 当 您 想 
要 直接 创建 一 个 表 对 象 时 ， 您 会 需要 把 它 放 在 那 : 


user favorites = db.Table('user favorites', 
db.Column('user id', db.Integer, db.ForeignKey('user.id')), 
db.Column('message id', db.Integer, db.ForeignKey('message.id')), 
info={'bind_key': 'users'} 


) 


如 果 您 在 模型 上 指定 了 _ bind key  ， 您 可 以 用 它们 准确 地 做 您 想 要 的 。 模 型 会 自行 连 接 
到 指定 的 数据 库 连 接 。 


信号 支持 
您 可 以 订阅 如 下 这 些 信 号 以 便 在 更 新 提交 到 数据 库 之 前 以 及 之 后 得 到 通知 。 
如 果 配 置 中 sQLALCHEMY_TRACK_MODIFICATIONS 启用 的 话 ， 这 些 更 新 变化 才能 被 追踪 。 
New in version 0.10. 
Changed in version 2.1: before_models_committed 正确 地 被 触发 。 
Deprecated since version 2.1: 在 以 后 的 版 本 中 ， 这 个 配置 项 默认 是 禁用 的 。 
存在 以 下 两 个 信号 : 
models_committed 


这 个 信号 在 修改 的 模型 提交 到 数据 库 时 发 出 。 发 送 者 是 发 送 修改 的 上 应用， 模型 和 操作 描述 符 
以 (model, operation) 形式 作为 元 组 ， 这 样 的 元 组 列表 传递 给 接受 者 的 changes SR, 


该 模型 是 发 送 到 数据 库 的 模型 实例 ， 当 一 个 模型 已 经 插入 ， 操 作 是 'insert' ， 而 已 删除 是 
'delete' ， 如 果 更 新 了 任何 列 ， 会 是 'update' o 


before models committed 


工作 机 制 和 models committed 完全 一 样 ， 但 是 在 提交 之 前 发 送 。 
API 
这 部 分 文档 记录 了 Flask-SQLAlchemy 里 的 所 有 公开 的 类 和 函数 。 


Ac iS 


class flask.ext.sqlalchemy.SQLAlchemy(app=None, use_native_unicode=True, session optionszN 


This class is used to control the SQLAlchemy integration to one or more Flask applications. 
Depending on how you initialize the object it is usable right away or will attach as needed to 
a Flask application. 


There are two usage modes which work very similarly. One is binding the instance to a very 
specific Flask application: 


app = Flask( name ) 
db = SQLAlchemy(app) 


The second possibility is to create the object once and configure the application later to 
support it: 


db - SQLAlchemy() 


def create app(): 
app = Flask( name ) 
db.init app(app) 
return app 


The difference between the two is that in the first case methods like create a11() and 
drop all() Will work all the time but in the second case a flask.Flask.app_context() has 
to exist. 


By default Flask-SQLAlchemy will apply some backend-specific settings to improve your 
experience with them. As of SQLAlchemy 0.6 SQLAIchemy will probe the library for native 
unicode support. If it detects unicode it will let the library handle that, otherwise do that itself. 
Sometimes this detection can fail in which case you might want to set use native unicode 
(or the soLALcHEMY NATIVE UNICODE configuration key) to False . Note that the configuration 
key overrides the value you pass to the constructor. 


This class also provides access to all the SQLAlchemy functions and classes from the 
sqlalchemy and sqlalchemy.orm modules. So you can declare models like this: 


class User(db.Model): 
username - db.Column(db.String(80), unique-True) 
pw hash = db.Column(db.String(80)) 


You can still use sqlalchemy and sqlalchemy.orm directly, but note that Flask-SQLAIchemy 
customizations are available only through an instance of this sorAichemy class. Query 
classes default to BaseQuery for db.Query , db.Model.query. class , and the default 

query class for db.relationship and db.backref . If you use these interfaces through 
sqlalchemy and sqlalchemy.orm directly, the default query class will be that of sqlalchemy . 


Check types carefully 


Don't perform type or isinstance checks against db.Table , which emulates Table 
behavior but is nota class. db.rable exposes the Table interface, but is a function which 
allows omission of metadata. 


You may also define your own SessionExtension instances as well when defining your 
SQLAlchemy class instance. You may pass your custom instances to the 

session extensions keyword. This can be either a single SessionExtension instance, or a 
list of SessionExtension instances. In the following use case we use the VersionedListener 
from the SQLAlchemy versioning examples.: 


from history meta import VersionedMeta, VersionedListener 


app = Flask( name ) 
db - SQLAlchemy(app, session extensions-[VersionedListener()]) 


class User(db.Model): 
__metaclass__ = VersionedMeta 
username = db.Column(db.String(80), unique=True) 
pw hash = db.Column(db.String(80)) 


The session options parameter can be used to override session options. If provided it's a 
dict of parameters passed to the session's constructor. 


New in version 0.10: The session options parameter was added. 


New in version 0.16: scopefunc is now accepted on session options . It allows specifying a 
custom function which will define the SQLAlchemy session's scoping. 


New in version 2.1: The metadata parameter was added. This allows for setting custom 
naming conventions among other, non-trivial things. 


Query 
The BaseQuery Class. 


apply_driver_hacks(app, info, options) 


This method is called before engine creation and used to inject driver specific hacks into the 
options. The options parameter is a dictionary of keyword arguments that will then be used 
to call the sqlalchemy.create_engine() function. 


The default implementation provides some saner defaults for things like pool sizes for 
MySQL and sqlite. Also it injects the setting of SQLALCHEMY_NATIVE_UNICODE . 


create all(bind-' all ', app=None) 


—— 


Creates all tables. 


Changed in version 0.12: Parameters were added 


create_scoped_session(options=None) 


Helper factory method that creates a scoped session. It internally calls create_session() . 


create session(options) 
Creates the session. The default implementation returns a signallingSession . 


New in version 2.0. 
drop all(bind-' all ', app=None) 
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Drops all tables. 
Changed in version 0.12: Parameters were added 
engine 


Gives access to the engine. If the database configuration is bound to a specific application 
(initialized with an application) this will always return a database connection. If however the 
current application is used this might raise a  RuntimeError if no application is active at the 
moment. 


get app(reference app-None) 

Helper method that implements the logic to look up an application. 
get binds(app-None) 

Returns a dictionary with a table->engine mapping. 

This is suitable for use of sessionmaker(binds-db.get binds(app)). 
get engine(app, bind-None) 

Returns a specific engine. 

New in version 0.12. 
get tables for bind(bind-None) 

Returns a list of all tables relevant for a bind. 
init app(app) 


This callback can be used to initialize an application for the use with this database setup. 
Never use a database in the context of an application not initialized that way or connections 
will leak. 


make connector(app, bind=None) 


Creates the connector for a given state and bind. 


make declarative base(model, metadata-None) 


Creates the declarative base. 


metadata 


Returns the metadata 


reflect(bind-' all ', app=None) 


— 4 


Reflects tables from the database. 


Changed in version 0.12: Parameters were added 


模型 


class flask.ext.sqlalchemy.Model 
Baseclass for custom user models. 
. bind key . 


Optionally declares the bind to use. None refers to the default bind. For more information 
see HES TRUE E. 


__tablename__ 


The name of the table in the database. This is required by SQLAlchemy; however, Flask- 
SQLAlIchemy will set it automatically if a model has a primary key defined. If the _ table - 
Or  tablename iS Set explicitly, that will be used instead. 


query - None 
an instance of query c1ass . Can be used to query the database for instances of this model. 


query class 


the query class used. The query attribute is an instance of this class. By default a 
BaseQuery is used. 


alias of BaseQuery 


class flask.ext.sqlalchemy.BaseQuery(entities, session=None) 


The default query object used for models, and exposed as Query . This can be subclassed 
and replaced for individual models by setting the «query c1ass attribute. This is a subclass of 
a standard SQLAlchemy Query class and has all the methods of a standard query as well. 


all() 


Return the results represented by this query as a list. This results in an execution of the 
underlying query. 


order by(*criterion) 


apply one or more ORDER BY criterion to the query and return the newly resulting query. 


limit(limit) 
Apply a LIMIT to the query and return the newly resulting query. 


offset(offset) 


Apply an OFFSET to the query and return the newly resulting query. 


first() 


Return the first result of this query or None if the result doesn't contain any rows. This 
results in an execution of the underlying query. 


first or 404() 


Like first() but aborts with 404 if not found instead of returning None . 


get(ident) 
Return an instance based on the given primary key identifier, or None if not found. 


E.g.: 


my_user = session.query(User).get(5) 


some_object = session.query(VersionedFoo).get((5, 10)) 


get() is special in that it provides direct access to the identity map of the owning session . 
If the given primary key identifier is present in the local identity map, the object is returned 
directly from this collection and no SQL is emitted, unless the object has been marked fully 
expired. If not present, a SELECT is performed in order to locate the object. 


get() also will perform a check if the object is present in the identity map and marked as 
expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still 
present. If not, objectpeletedError is raised. 


get() is only used to return a single mapped instance, not multiple instances or individual 
column constructs, and strictly on a single primary key value. The originating Query must 
be constructed in this way, i.e. against a single mapped entity, with no additional filtering 
criterion. Loading options via options() may be applied however, and will be used if the 
object is not yet locally present. 


A lazy-loading, many-to-one attribute configured by relationship() , using a simple foreign- 

key-to-primary-key criterion, will also use an operation equivalentto get() in order to 

retrieve the target value from the local identity map before querying the database. See 
/orm/loading relationships for further details on relationship loading. 


Parameters: ident -Ascalar ortuple value representing the primary key. For a composite 
primary key, the order of identifiers corresponds in most cases to that of the mapped Table 
object's primary key columns. Fora mapper() that was given the primary key argument 
during construction, the order of identifiers corresponds to the elements present in this 
collection. 


Returns: The object instance, or None . 


get or A04(ident) 


Like get() but aborts with 404 if not found instead of returning wone . 


paginate(page=None, per_page=None, error out-True) 


Returns per page items from page page . By default it will abort with 404 if no items were 
found and the page was larger than 1. This behavor can be disabled by setting error out 
to False. 


If page or per. page are None, they will be retrieved from the request query. If the values are 
not ints and error out is true, it will abort with 404. If there is no request or they aren't in 
the query, they default to page 1 and 20 respectively. 


Returns an Pagination object. 


P 
会 话 
class flask.ext.sqlalchemy.SignallingSession(db, autocommit-False, autoflush=True, app=Non: 


The signalling session is the default session that Flask-SQLAlchemy uses. It extends the 
default session system with bind selection and modification tracking. 


If you want to use a different session you can override the sor Aichemy.create session() 
function. 


New in version 2.0. 


New in version 2.1: The binds option was added, which allows a session to be joined to an 
external transaction. 


app - None 


The application that this session belongs to. 


实用 工具 


class flask.ext.sqlalchemy.Pagination(query, page, per_page, total, items) 


Internal helper class returned by BaseQuery.paginate() . You can also construct it from any 
other SQLAlchemy query object if you are working with other libraries. Additionally it is 
possible to pass None as query object in which case the prev() and next() will no longer 
work. 


has next 


True if a next page exists. 


has prev 


True if a previous page exists 


items - None 


the items for the current page 


iter pages(left edge-2, left current-2, right current-5, right edge-2) 


Iterates over the page numbers in the pagination. The four parameters control the thresholds 
how many numbers should be produced from the sides. Skipped page numbers are 
represented as wone . This is how you could render such a pagination in the templates: 


(96 macro render pagination(pagination, endpoint) %} 
class=pagination> 
{%- for page in pagination.iter_pages() %} 
{% if page %} 
{% if page != pagination.page %} 
<a href="{{ url_for(endpoint, page=page) }}">{{ page }}</a> 
{% else %} 
<strong>{{ page }}</strong> 
{% endif %} 
{% else %} 
class=ellipsis>... 
{% endif %} 
{%- endfor %} 


{% endmacro %} 


next (error_out=False) 
Returns a Pagination object for the next page. 
next_num 
Number of the next page 
page = None 
the current page number (1 indexed) 
pages 


The total number of pages 


per_page = None 


the number of items to be displayed on a page. 
prev(error_out=False) 
Returns a Pagination object for the previous page. 
prev_num 
Number of the previous page. 
query = None 
the unlimited query object that was used to create this pagination object. 
total = None 
the total number of items matching the query 


flask.ext.sqlalchemy.get_debug_queries() 


In debug mode Flask-SQLAlchemy will log all the SQL queries sent to the database. This 
information is available until the end of request which makes it possible to easily ensure that 
the SQL generated is the one expected on errors or in unittesting. If you don’t want to enable 
the DEBUG mode for your unittests you can also enable the query recording by setting the 

'SQLALCHEMY RECORD QUERIES' config variable to True . This is automatically enabled if Flask 
is in testing mode. 


The value returned will be a list of named tuples with the following attributes: 


statement 
The SQL statement issued 
parameters 
The parameters for the SQL statement 
start_time / end_time 


Time the query started / the results arrived. Please keep in mind that the timer function used 
depends on your platform. These values are only useful for sorting or comparing. They do 
not necessarily represent an absolute timestamp. 


duration 
Time the query took in seconds 


context 


A string giving a rough estimation of where in your application query was issued. The exact 
format is undefined so don't try to reconstruct filename or function name. 


更 新 历史 


在 这 里 您 可 以 看 到 每 一 个 Flask-SQLAlchemy 发 布 版 本 的 变化 的 完整 列表 。 


Version 2.1 


In development 


e Table names are automatically generated in more cases, including subclassing mixins 
and abstract models. 


Version 2.0 


Released on August 29th 2014, codename Bohrium 


e Changed how the builtin signals are subscribed to skip non Flask-SQLAlchemy 
sessions. This will also fix the attribute error about model changes not existing. 

e Added a way to control how signals for model modifications are tracked. 

e Made the signallingsession a public interface and added a hook for customizing 
session creation. 

e |fthe bind parameter is given to the signalling session it will no longer cause an error 
that a parameter is given twice. 

e Added working table reflection support. 

e Enabled autoflush by default. 

e Consider sqLALcHEMY. coMMIT ON TEARDOWN harmful and remove from docs. 


Version 1.0 


Released on July 20th 2013, codename Aurum 


e Added Python 3.3 support. 
Dropped 2.5 compatibility. 


e Various bugfixes 


Changed versioning format to do major releases for each update now. 


Version 0.16 


e New distribution format (flask sglalchemy) 
e Added support for Flask 0.9 specifics. 


Version 0.15 


e Added session support for multiple databases 


Version 0.14 


e Make relative sqlite paths relative to the application root. 


Version 0.13 


e Fixed an issue with Flask-SQLAlchemy not selecting the correct binds. 


Version 0.12 


e Added support for multiple databases. 

e Expose Flask-SQLAlchemy's BaseQuery as db.Query . 

e Set default query class for db.relation , db.relationship , and db.dynamic loader tO 
Flask-SQLAlchemy's BaseQuery. 

e Improved compatibility with Flask 0.7. 


Version 0.11 


e Fixed a bug introduced in 0.10 with alternative table constructors. 


Version 0.10 


e Added support for signals. 

e Table names are now automatically set from the class name unless overriden. 

e Model.query now always works for applications directly passed to the SQLAlchemy 
constructor. Furthermore the property now raises an RuntimeError instead of being 
None. 

e added session options to constructor. 

e fixed a broken | repr. 

e db.Table is now a factor function that creates table objects. This makes it possible to 
omit the metadata. 


Version 0.9 


e applied changes to pass the Flask extension approval process. 


Version 0.8 


e added a few configuration keys for creating connections. 
e automatically activate connection recycling for MySQL connections. 
e added support for the Flask testing mode. 


Version 0.7 


e Initial public release 


Flask-Testing 


Flask-Testing 扩展 为 Flask 提供 了 单元 测试 的 工具 。 


安装 Flask-Testing 
使 用 pip 或 者 easy_install 安装 : 


pip install Flask-Testing 


或 者 从 版 本 控制 系统 (github) 中 下 载 最 新 的 版 本 : 


git clone https://github.com/jarus/flask-testing.git 
cd flask-testing 
python setup.py develop 


如 果 你 正在 使 用 virtualenv， 假 设 你 会 安装 Flask-Testing 在 运行 你 的 Flask 应 用 程序 的 同一 
个 virtualenv 上 。 


编导 测试 用 例 
简单 地 继承 Testcase 的 MyTest: 


from flask.ext.testing import TestCase 
class MyTest(TestCase): 


pass 


你 必须 定义 create app 方法 ， 该 方法 返回 一 个 Flask 实例 : 
from flask import Flask 
from flask.ext.testing import TestCase 
class MyTest(TestCase): 
def create app(self): 
app = Flask( name ) 


app.config['TESTING'] - True 
return app 


如 果 不 定 义 create app , NotImplementedError 异常 将 会 抛 出 。 


使 用 LiveServer 测试 


如 果 你 想 要 你 的 测试 通过 Selenium 或 者 无 头 浏 览 器 (无 头 浏 览 器 的 意思 就 是 无 外 设 的 意思 ， 
可 以 在 命令 行 下 运行 的 浏览 器 ) 运 行 ， 你 可 以 使 用 LiveServerTestCase: 


import urllib2 
from flask import Flask 
from flask.ext.testing import LiveServerTestCase 


class MyTest(LiveServerTestCase): 


def create app(self): 
app = Flask( name ) 
app.config['TESTING'] - True 
# Default port is 5000 
app.config['LIVESERVER PORT'] = 8943 
return app 


def test server is up and running(self): 
response - urllib2.urlopen(self.get server url()) 
self.assertEqual(response.code, 200) 





在 这 个 例子 中 get server ur1. 方法 将 会 返回 http://localhost:8943, 


测试 JSON 响应 


如 果 你 正在 测试 一 个 返回 JSON 的 视图 函数 的 话 ， 你 可 以 使 用 Response 对 象 的 特殊 的 属性 
json 来 测试 输出 : 
@app.route("/ajax/") 
def some_json(): 
return jsonify(success=True) 
class TestViews(TestCase): 
def test some json(self): 


response - self.client.get("/ajax/") 
self.assertEquals(response.json, dict(success-True)) 


选择 不 泻 染 模板 


当 测 试 需要 处 理 模 板 泻 染 的 时 候 可 能 是 一 个 大 问题 。 如 果 在 测试 中 你 不 想 要 泻 染 模板 的 话 可 
以 设置 render_templates 属性 : 


class TestNotRenderTemplates(TestCase): 
render templates - False 


def test assert not process the template(self): 
response - self.client.get("/template/") 


assert "" == response.data 


尽管 可 以 设置 不 想 泻 染 模板 ， 但 是 演 染 模板 的 信号 在 任何 时 候 都 会 发 送 ， 你 也 可 以 使 用 
assert template used 方法 来 检查 模板 是 否 被 泻 染 : 


class TestNotRenderTemplates(TestCase): 
render templates - False 


def test assert mytemplate used(self): 
response - self.client.get("/template/") 


self.assert template used('mytemplate.html') 


当 泻 染 模 板 被 关闭 的 时 候 ， 测 试 执行 起 来 会 更 加 的 快速 并 且 视 图 图 数 的 逻辑 将 会 孤立 地 被 测 
试 。 


使 用 Twill 

Twill 是 一 个 用 来 通过 使 用 命令 行 界 面 浏览 网 页 的 简单 的 语言 。 

Note 

请 注意 Twill 只 支持 Python 2.x， 不 能 在 Python 3 或 者 以 上 版 本 上 使 用 。 
Flask-Testing 拥有 一 个 辅助 类 用 来 创建 使 用 Twill 的 功能 测试 用 例 : 
def test something with twill(self): 


with Twill(self.app, port=3000) as t: 
t.browser.go(t.url("/")) 


旧 的 TwillTestcase 类 已 经 被 弃 用 。 


测试 SQLAlchemy 


这 部 分 将 会 涉及 使 用 Flask-Testing 测试 SQLAlchemy 的 一 部 分 内 容 。 这 里 假设 你 使 用 的 是 
Flask-SQLAlchemy 扩展 ， 并 且 这 里 的 例子 也 不 是 太 难 ， 可 以 适用 于 用 户 自 己 的 配置 。 


首先 ， 先 确保 数据 库 的 URI 是 设置 成 开发 环境 而 不 是 生产 环境 ! 其 次 ， 一 个 好 的 测试 习惯 就 
是 在 每 一 次 测试 执行 的 时 候 先 创建 表 ， 在 结束 的 时 候 删 除 表 ， 这 样 保证 干净 的 测试 环境 : 


from flask.ext.testing import TestCase 
from myapp import create app, db 
class MyTest(TestCase): 


SQLALCHEMY DATABASE URI = "sqlite://" 
TESTING - True 


def create app(self): 


pass in test configuration 
return create app(self) 


def setUp(self): 
db.create all() 
def tearDown(self): 


db.session.remove() 
db.drop all() 


同样 需要 注意 地 是 每 一 个 新 的 SQLAIchemy 会 话 在 测试 用 例 运 行 的 时 候 就 被 创建 ， 
db.session.remove() 在 每 一 个 测试 用 例 的 结尾 被 调用 (这 是 为 了 确保 SQLAlchemy 会 话 及 时 

被 删除 ) - 这 是 一 种 常见 的 “陷阱 ”。 

另外 一 个 “陷阱 ” 就 是 Flask-SQLAlchemy 会 在 每 一 个 请 求 结 束 的 时 候 删 除 SQLAlchemy 会 话 
(session)。 因 此 每 次 调用 client.get() 或 者 其 它 客户 端 方法 的 后 ，SQLAIchemy 会 话 
(session) 连 同 添加 到 它 的 任何 对 象 都 会 被 删除 。 


例如 : 


class SomeTest(MyTest): 
def test something(self): 
user - User() 
db.session.add(user) 


db.session.commit() 


# this works 
assert user in db.session 


response - self.client.get("/") 


# this raises an AssertionError 
assert user in db.session 


你 现在 必须 重新 添加 “user 实例 回 SQLAlchemy 会 话 (session) 使 用 db.session.add(user) , 
如 果 你 想 要 在 数据 库 上 做 进一步 的 操作 。 


同样 需要 注意 地 是 在 这 个 例子 中 内 存 数据 库 SQLite 是 被 使 用 : 尽管 它 是 十 分 的 快 ， 但 是 你 要 
是 使 用 其 它 类 型 的 数据 库 ( 例 如 MySQL 或 者 PostgreSQL)， 可 能 上 述 代码 就 不 适用 。 


你 也 可 能 想 要 在 setup() 里 为 你 的 数据 库 增 加 一 组 实例 一 旦 你 的 数据 库 的 表 已 经 创建 。 如 果 
你 想 要 使 用 数据 集 的 话 ， 请 参看 Fixture, CAST xt SQLAlchemy 的 支持 。 


运行 测试 用 例 
使 用 unittest 


一 开始 我 建议 把 所 有 的 测试 放 在 一 个 文件 里 面 ， 这 样 你 可 以 使 用 unittest.main() 图 数 。 这 
个 函数 将 会 发 现在 你 的 Testcase 类 里 面 的 所 有 的 测试 方法 。 请 记 住 ， 所 有 的 测试 方法 和 类 
请 以 test 开头 (不 区 分 大 小 写 ) ， 这 样 才能 被 自动 识别 出 来 。 


一 个 测试 用 例 的 文件 可 以 看 起 来 像 这 样 : 
Import Unittest 
import flask.ext.testing 
# your test cases 


if name == ' main 
unittest.main() 





现在 你 可 以 用 python tests.py 命令 执行 你 的 测试 。 


使 用 nose 


同样 nose 也 与 Flask-Testing 能 够 很 好 的 融合 在 一 起 。 


更 新 历史 


0.4.2 (24.07.2014) 


>> 


e Improved teardown to be more graceful. 
e Add message argumentto assertStatus respectively all assertion methods with 


fixed status like assert4o4 . 


0.4.1 (27.02.2014) 


This release is dedicated to every contributer who made this release possible. Thank you 
very much. 


>> 


Python 3 compatibility (without twill) 


Add LiveserverTestCase 
e Use unittest2 backports if available in python 2.6 
e Install multiprocessing for python versions earlier than 2.6 


0.4 (06.07.2012) 


>> 


Use of the new introduced import way for flask extensions. Use 


import flask.ext.testing instead of import flaskext.testing . 


Replace all assert with self.assert* methods for better output with unittest. 


Improved Python 2.5 support. 


Use Flask’s preferred JSON module. 


API 


class flask.ext.testing.TestCase(methodName-'runTest') 


assert200(response) 

Checks if response status code is 200 

Parameters: response — Flask response 
assert400(response) 

Checks if response status code is 400 

Versionadded: 0.2.5 

Parameters: response — Flask response 
assert401(response) 

Checks if response status code is 401 

Versionadded: 0.2.1 

Parameters: response — Flask response 
assert403(response) 

Checks if response status code is 403 

Versionadded: 0.2 


Parameters: response - Flask response 


assert404(response) 


Checks if response status code is 404 


Parameters: response - Flask response 


assert405(response) 
Checks if response status code is 405 
Versionadded: 0.2 


Parameters: response - Flask response 


assert500(response) 
Checks if response status code is 500 
Versionadded: 0.4.1 


Parameters: response — Flask response 


assertContext(name, value) 

Checks if given name exists in the template context and equals the given value. 
Versionadded: 

0.2 

Parameters: 


e name — name of context variable 
e value - value to check against 


assertRedirects(response, location) 
Checks if response is an HTTP redirect to the given location. 
Parameters: 


e response - Flask response 
e location — relative URL (i.e. without http://localhost) 


assertStatus(response, status code) 
Helper method to check matching response status. 
Parameters: 


e response - Flask response 
e status code — response status code (e.g. 200) 


assertTemplateUsed(name, tmpl name attribute-'name!') 


Checks if a given template is used in the request. Only works if your version of Flask has 
signals support (0.6+) and blinker is installed. If the template engine used is not Jinja2, 
provide tmpl name attribute with a value of its Template class attribute name which 
contains the provided name value. 


Versionadded: 
0.2 
Parameters: 


e name — template name 
e tmpl name attribute — template engine specific attribute name 


assert 200(response) 
Checks if response status code is 200 


Parameters: response - Flask response 


assert 400(response) 
Checks if response status code is 400 
Versionadded: 0.2.5 


Parameters: response - Flask response 


assert 401(response) 
Checks if response status code is 401 
Versionadded: 0.2.1 


Parameters: response - Flask response 


assert 403(response) 
Checks if response status code is 403 
Versionadded: 0.2 


Parameters: response - Flask response 


assert 404(response) 
Checks if response status code is 404 


Parameters: response - Flask response 


assert 405(response) 


Checks if response status code is 405 


Versionadded: 0.2 


Parameters: response - Flask response 
assert 500(response) 


Checks if response status code is 500 


Versionadded: 0.4.1 Parameters: response — Flask response 


assert context(name, value) 


Checks if given name exists in the template context and equals the given value. 


Versionadded: 
0.2 
Parameters: 


e name — name of context variable 
e value - value to check against 


assert redirects(response, location) 
Checks if response is an HTTP redirect to the given location. 
Parameters: 


e response - Flask response 
e location — relative URL (i.e. without http://localhost) 


assert status(response, status code) 
Helper method to check matching response status. 
Parameters: 


e response - Flask response 
e status code - response status code (e.g. 200) 


assert template used(name, tmpl name attribute-'name') 


Checks if a given template is used in the request. Only works if your version of Flask has 


signals support (0.6+) and blinker is installed. If the template engine used is not Jinja2, 


provide tmpl name attribute with a value of its Template class attribute name which 


contains the provided name value. 
Versionadded: 
0.2 


Parameters: 


e name — template name 
e tmpl name attribute — template engine specific attribute name 


create app() 


Create your Flask app here, with any configuration you need. 


get context variable(name) 


Returns a variable from the context passed to the template. Only works if your version of 
Flask has signals support (0.6+) and blinker is installed. 


Raises a ContextVariableDoesNotExist exception if does not exist in context. 
Versionadded: 0.2 


Parameters: name — name of variable 


class flask.ext.testing.Twill(app, host='127.0.0.1', port=5000, scheme='http' ) 
Versionadded: 0.3 
Twill wrapper utility class. 
Creates a Twill browser instance and handles WSGI intercept. 


Usage: 


t - Twill(self.app) 

with t: 
t.browser.go("/") 
t.url("/") 


url(url) 
Makes complete URL based on host, port and scheme Twill settings. 


Parameters: url — relative URL 


class flask.ext.testing.TwillTestCase(methodName-'runTest') 
Deprecated: use Twill helper class instead. 
Creates a Twill browser instance and handles WSGI intercept. 

make twill url (url) 

Makes complete URL based on host, port and scheme Twill settings. 


Parameters: url — relative URL 


Flask-WTF 


Flask-WTF 提供 了 简单 地 WTForms 的 集成 。 


功能 
。 集成 wtforms。 
e 带 有 csrf 今 牌 的 安全 表单 。 
。 全 局 的 csrf 保护 。 
e 支持 验证 码 (Recaptcha) 。 
。 与 Flask-Uploads 一 起 支持 文件 上 传 。 
。 国际 化 集成 。 


mo yt 
BR 

该 部 分 文档 涵盖 了 Flask-WTF 安装 。 使 用 任何 软件 包 的 第 一 步 即 是 正确 安装 它 。 
Distribute & Pip 


用 pip 安装 Flask-WTF 是 十 分 简单 的 : 


$ pip install Flask-WTF 


或 者 ， 使 用 easy_install: 


$ easy install Flask-WTF 
但 是 ， 你 真 的 不 应 该 这 样 做 。 
获取 源 代 码 


Flask-WTF 在 GitHub 上 活跃 开发， 代码 在 GitHub 上 始终 可 用 。 


你 也 可 以 克隆 公开 仓库 : 


git clone git://github.com/lepture/flask-wtf.git 


下 载 tarball: 


$ curl -OL https://github.com/lepture/flask-wtf/tarball/master 


或 者 ， 下 载 zipball: 


$ curl -OL https://github.com/lepture/flask-wtf/zipball/master 
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packages: 


$ python setup.py install 


IER EAT] 


急于 上 手 ? 本 页 对 Flask-WTF 给 出 了 一 个 详尽 的 介绍 。 假 设 你 已 经 安装 了 Flask-WTF， 如 果 
还 未 安装 的 话 ， 请 先 浏 览 安装 。 


创建 表单 
Flask-WTF 提供 了 对 WTForms 的 集成 。 例 如 


from flask wtf import Form 
from wtforms import StringField 
from wtforms.validators import DataRequired 


class MyForm(Form): 
name - StringField('name', validators-[DataRequired()]) 


Note 


从 0.9.0 版 本 开始 ，Flask-WTF 将 不 会 从 wtforms 中 导入 任何 的 内 容 ， 用 户 必须 自己 从 
wtforms 中 导入 字段 。 


另外 ， 降 藏 的 CSRF 令 牌 会 被 自动 地 创建 。 你 可 以 在 模板 这 样 地 泻 染 它 : 


<form method="POST" action="/"> 
{{ form.csrf_token }} 
{{ form.name.label }} {{ form.name(size-20) }} 
«input type="submit" value="Go"> 

</form> 


尽管 如 此 ， 为 了 创建 有 效 的 XHTML/HTML， Form 类 有 一 个 hidden tag 方法 ， 它 在 一 个 隐 
藏 的 DIV 标签 中 泻 染 任何 隐藏 的 字段 ， 包 括 CSRF FR: 


«form method="POST" action="/"> 
{{ form.hidden_tag() }} 
{{ form.name.label }} {{ form.name(size=20) }} 
<input type="submit" value="Go"> 

</form> 


验证 表单 
在 你 的 视图 义理 程序 中 验证 请 求 : 


@app.route('/submit', methods=('GET', 'POST')) 
def submit(): 
form = MyForm() 
if form.validate_on_submit(): 
return redirect('/success' ) 
return render template('submit.html', form=form) 


注意 你 不 需要 把 request.form 传 给 Flask-WTF ; Flask-WTF 会 自动 加 载 。 便 捷 的 方法 
validate on submit 将 会 检查 是 否 是 一 个 POST 请 求 并 且 请 求 是 否 有 效 。 


阅读 创建 表单 学 习 更 多 的 关于 表单 的 技巧 。 


创建 表单 
这 部 分 文档 涉及 表单 (Form) 信 息 。 
安全 表单 


无 需 任何 配置 ， Form 是 一 个 带 有 CSRF 保护 的 并 且 会 话 安 全 的 表单 。 我 们 鼓励 你 什么 都 不 
做 。 


但 是 如 果 你 想 要 茶 用 CSRF 保护 ， 你 可 以 这 样 : 


form = Form(csrf enabled-False) 


如 果 你 想 要 全 局 茶 用 CSRF 保护 ， 你 真 的 不 应 该 这 样 做 。 但 是 你 要 坚持 这 样 做 的 话 ， 你 可 以 
在 配置 中 这 样 写 : 


WTF_CSRF_ENABLED = False 


为 了 生成 CSRF 倒 牌 ， 你 必须 有 一 个 密 钥 ， 这 通常 与 你 的 Flask 应 用 密 钥 一 致 。 如 果 你 想 使 
用 不 同 的 密 钥 ， 可 在 配置 中 指定 : 


WTF CSRF SECRET KEY = 'a random string' 


文件 上 传 


Flask-WTF 提供 FileField 来 处 理 文件 上 传 ， 它 在 表单 提交 后 ， 自 动 从 


flask.request.files 中 抽取 数据 。 FileField 的 data 属性 是 一 个 Werkzeug FileStorage 


实例 。 


例如 : 


from werkzeug import secure filename 
from flask wtf.file import FileField 


class PhotoForm(Form): 
photo - FileField('Your photo') 


Qapp.route('/upload/', methods-('GET', 'POST')) 
def upload(): 
form - PhotoForm() 
if form.validate on submit(): 
filename - secure filename(form.photo.data.filename) 
form.photo.data.save('uploads/' + filename) 
else: 
filename - None 
return render template('upload.html', form-form, filename-filename) 


Note 


记得 把 你 的 HTML 表单 的 enctype 设置 成 multipart/form-data , Bes: 


«form action="/upload/" method="POST" enctype="multipart/form-data"> 


</form> 


此 外 ，Flask-WTF 支持 文件 上 传 的 验证 。 提 供 了 FileRequired 和 FileAllowed o 


FileAllowed 能 够 很 好 地 和 Flask-Uploads 一 起 协同 工作 , 例如 : 


from flask.ext.uploads import UploadSet, IMAGES 
from flask wtf import Form 
from flask wtf.file import FileField, FileAllowed, FileRequired 


images - UploadSet('images', IMAGES) 


class UploadForm(Form): 
upload - FileField('image', validators-[ 
FileRequired(), 
FileAllowed(images, 'Images only!') 


]) 


也 能 在 没有 Flask-Uploads 下 挑大梁 。 这 时 候 你 需要 向 rileallowed 传人 扩展 名 即 可 : 


class UploadForm(Form): 
upload - FileField('image', validators-[ 
FileRequired(), 
FileAllowed(['jpg', 'png'], 'Images only!') 
]) 


HTML5 控件 


Note 


Bl wtforms 1.0.5 版 本 开始 ，wtforms RAR T HTML5 控件 和 字段 。 如 果 可 能 的 话 ， 你 可 以 
考虑 从 wtforms 中 导 和 它们 。 


我 们 将 会 在 0.9.3 版 本 后 移 除 html5 模块 。 
你 可 以 从 wtforms 中 导入 一 些 HTML5 控件 : 


from wtforms.fields.html5 import URLField 
from wtforms.validators import url 


class LinkForm(Form): 
url - URLField(validators-[url()]) 


验证 码 
Flask-WTF 通过 Recaptcharield 也 提供 对 验证 码 的 支持 : 


from flask wtf import Form, RecaptchaField 
from wtforms import TextField 


class SignupForm(Form): 
username - TextField('Username') 
recaptcha - RecaptchaField() 


这 伴随 着 诸多 配置 ， 你 需要 逐一 地 配置 它们 。 


RECAPTCHA_PUBLIC_KEY 必须 公 铀 

RECAPTCHA PRIVATE KEY ”必须 私 钥 

RECAPTCHA API SERVER 可 选 验证 码 API 服务 器 

RECAPTCHA PARAMETERS ， 可 选 一 个 JavaScript (api.js) 参数 的 字典 


可 选 一 个 数据 属性 项 列表 


NEAR TOHAL DATACATTRS https://developers.google.com/recaptcha/docs/display 


RECAPTCHA PARAMETERS 和 RECAPTCHA DATA ATTRS 的 示例 : 


RECAPTCHA_PARAMETERS 
RECAPTCHA_DATA_ATTRS 


['hl': 'zh', 'render': 'explicit') 
{'theme': 'dark'} 


EN 
7 


对 于 应 用 测试 时 ， 如 果 app.testing 为 True ， 考 虑 到 方便 测试 ，Recaptcha 字段 总 是 有 效 
的 。 


在 模板 中 很 容易 添加 Recaptcha 字段 : 


«form action="/" method="post"> 
{{ form.username }} 
{{ form.recaptcha }} 
</form> 


我 们 为 你 提供 了 例子 : recaptcha@github. 


CSRF 保护 


这 部 分 文档 介绍 了 CSRF 保护 。 


为 什么 需要 CSRF ? 
Flask-WTF 表单 保护 你 免 受 CSRF 威胁 ， 你 不 需要 有 任何 担心 。 尽 管 如 此 ， 如 果 你 有 不 包含 
表单 的 视图 ， 那 么 它们 仍 需 要 保护 。 


例如 ， 由 AJAX 发 送 的 POST 请 求 ， 然 而 它 背 后 并 没有 表单 。 在 Flask-WTF 0.9.0 以 前 的 版 
本 你 无 法 获得 CSRF 使 牌 。 这 是 为 什么 我 们 要 实现 CSRF。 


实现 


为 了 能 够 让 所 有 的 视图 函数 受到 CSRF 保护 ， 你 需要 开局 CsrfProtect 模块 : 


from flask wtf.csrf import CsrfProtect 


CsrfProtect(app) 


像 任何 其 它 的 Flask 扩展 一 样 ， 你 可 以 惰性 加 载 它 : 


from flask wtf.csrf import CsrfProtect 
csrf = CsrfProtect() 
def create app(): 


app = Flask( name ) 
csrf.init app(app) 


Note 
你 需要 为 CSRF 保护 设置 一 个 秘 钥 。 通 党 下 ， 同 Flask 应 用 的 SECRET. KEY 是 一 样 的 。 


如 果 模 板 中 存在 表单 ， 你 不 需要 做 任何 事情 。 与 之 前 一 祥 : 


«form method="post" action="/"> 
{{ form.csrf_token }} 
</form> 


但 是 如 果 模 板 中 没有 表单 ， 你 仍然 需要 一 个 CSRF The: 


«form method="post" action="/"> 
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}" /> 
</form> 


无 论 何 时 未 通过 CSRF 验证 ， 都 会 返回 400 响应 。 你 可 以 自 定 义 这 个 错误 响应 : 


Qcsrf.error handler 
def csrf error(reason): 
return render template('csrf error.html', reason=reason), 400 


我 们 强烈 建议 你 对 所 有 视图 启用 CSRF 保护 。 但 也 提供 了 某 些 视图 函数 不 需要 保护 的 装饰 器 : 


@csrf.exempt 
Qapp.route('/foo', methods-('GET', 'POST')) 
def my handler(): 

Ho... 

return 'ok' 


默认 情况 下 你 也 可 以 在 所 有 的 视图 中 禁用 CSRF 保护 ， 通 过 设置 wrF CSRF CHECK DEFAULT 为 
False ， 仅 仅 当 你 需要 的 时 候选 择 调用 csrf.protect() 。 这 也 能 够 让 你 在 检查 CSRF 兮 牌 前 
做 一 些 预先 义理 : 


Qapp.before request 
def check csrf(): 
if not is oauth(request): 
csrf.protect() 


AJAX 


不 需要 表单 ， 通 过 AJAX 发 送 POST 请 求 成 为 可 能 。0.9.0 版 本 后 这 个 功能 变 成 可 用 的 。 


假设 你 已 经 使 用 了 csrfProtect(app) ， 你 可 以 通过 ££ csrf_token() }} 获取 CSRF 兮 牌 。 
这 个 方法 在 每 个 模板 中 都 可 以 使 用 ， 你 并 不 需要 担心 在 没有 表单 时 如 何 泻 染 CSRF AE 
段 。 


我 们 推荐 的 方式 是 在 «meta» 标签 中 泻 染 CSRF 兮 牌 : 


«meta name="csrf-token" content="{{ csrf token() }}"> 


在 «script» 标签 中 泻 染 同样 可 行 : 


«script type="text/javascript"> 
var csrftoken = "{{ csrf token() }}" 
</script> 


下 面 的 例子 采用 了 在 «meta» 标签 泻 染 的 方式 ， 在 <script> RAB Gs, (MAD 
没有 相应 的 例子 


无 论 何 时 你 发 送 AJAX POST 请 求 ， 为 其 添加 x-csRFToken X: 


var csrftoken = $('meta[name-csrf-token]').attr('content') 


$.ajaxSetup({ 
beforeSend: function(xhr, settings) { 
if (!/^(GET|HEAD|OPTIONS|TRACE)$/i.test(settings.type) && !this.crossDomain) { 
xhr.setRequestHeader("X-CSRFToken", csrftoken) 
} 


}) 


ur 
故障 排除 
当 你 定义 你 的 表单 的 时 候 ， 如 果 犯 了 这 个 错误 MÅ wtforms 中 导入 Form 而 不 是 从 
flask.ext.wtf 中 导入 ，CSREF 保护 的 大 部 分 功能 都 能 工作 (除了 
form.validate on submit() )， 但 是 CSRF adc oS s 在 提交 表单 的 时 候 ， 你 将 会 得 


到 Bad Request | CSRF token missing or incorrect 错误 。 这 个 车 误 的 出 现 就 是 因为 你 的 导入 
ik, 而 不 是 你 的 配置 问题 。 


Roi 


这 里 是 所 有 配置 的 全 表 。 


表单 和 CSRF 


Flask-WTF 完整 的 配置 清单 。 通 常 ， 你 不 必 配 置 它 们 。 默 认 的 配置 就 能 正常 工作 。 


WTF_CSRF_ENABLED 禁用 /开启 表单 的 CSRF IRF ANER Éo 


默认 下 启用 CSRF 检查 针对 所 有 的 视图 。 默认 值 是 
True。 


禁用 /开启 118N 支持 。 需 要 和 Flask-Babel 配合 一 起 
使 用 。 默 认 是 开局。 


需要 检验 的 CSRF 兮 牌 HTTP ko EA [X- 
CSRFToken', ‘X-CSRF-Token’] 


一 个 随机 字符 串 生 成 CSRF SHH. Rif 
SECRET KEY 一 样 。 


WTF CSRF TIME LIMIT CSRF 兮 牌 过 期 时 间 。 默 认 是 3600 秒 。 


使 用 SSL 时 进行 严格 保护 。 这 会 检查 HTTP 
Referrer， 验证 是 否 同 源 。 默 认为 True 。 


使 用 CSRF 保护 的 HTTP 方法 。 默 认 是 ['POST，， 
‘PUT’, ‘PATCH’] 


WTF_CSRF_CHECK_DEFAULT 
WTF_I18N_ENABLED 
WTF_CSRF_HEADERS 


WTF_CSRF_SECRET_KEY 


WTF_CSRF_SSL_STRICT 


WTF_CSRF_METHODS 


WTF_HIDDEN_TAG 隐藏 的 HTML 标签 包装 的 名 称 。 默认 是 div 


隐藏 的 HTML 标签 包装 的 标签 属性 。 默认 是 


WTF HIDDEN TAG ATTRS í s. bat , 
a = = {‘style’: ‘display:none;’} 


验证 码 

你 已 经 在 验证 码 中 了 解 了 这 些 配置 选项 。 该 表 为 了 方便 速 查 。 

RECAPTCHA USE SSL 允许 /禁用 Recaptcha 使 用 SSL, MÆ False, 
RECAPTCHA_PUBLIC_KEY 必须 公 钥 。 


RECAPTCHA PRIVATE KEY ”必须 私 钥 。 


可 选 配置 选项 的 字典 。 


ot ETON https://www.google.com/recaptcha/admin/create 


开发 者 接口 


该 部 分 文档 涵盖 了 Flask-WTF 的 全 部 接口 。 


表单 和 字段 


class flask wtf.Form(formdata-«class flask wtf.form. Auto at 0x10627ed50>, obj=None, prefi: 


Flask-specific subclass of WTForms SecureForm class. 


If formdata is not specified, this will use flask.request.form. Explicitly pass formdata = None 
to prevent this. 


Parameters: 


e csrf context — a session or dict-like object to use when making CSRF tokens. Default: 
flask.session. 
e secret key — 


a secret key for building CSRF tokens. If this isn't specified, the form will take the first of 
these that is defined: 


o SECRET KEY attribute on this class 
o WTF CSRF SECRET KEY config of flask app 
o SECRET KEY config of flask app 
o session secret key 
e csrf enabled — whether to use CSRF protection. If False, all csrf behavior is 
suppressed. Default: WTF CSRF. ENABLED config value 


hidden tag(*fields) 
Wraps hidden fields in a hidden DIV tag, in order to keep XHTML compliance. 
New in version 0.3. 


Parameters: fields — list of hidden field names. If not provided will render all hidden fields, 
including the CSRF field. 


is submitted() 


Checks if form has been submitted. The default case is if the HTTP method is PUT or 
POST. 


validate csrf data(data) 


Check if the csrf data is valid. 


Parameters: data — the csrf string to be validated. 


validate on submit() 


Checks if form has been submitted and if so runs validate. This is a shortcut, equivalent to 
form.is submitted() and form.validate() 


class flask wtf.RecaptchaField(label-'', validators=None, **kwargs) 
class flask wtf.Recaptcha(message-None) 
Validates a ReCaptcha. 


class flask wtf.Recaptchawidget 


class flask wtf.file.FileField(label-zNone, validators=None, filters=(), description=u'', i: 
Werkzeug-aware subclass of wtforms.FileField 


Provides a has file() method to check if its data is a FileStorage instance with an actual 
file. 


has file() 


Return True iff self.data is a FileStorage with file data 


class flask wtf.file.FileAllowed(upload set, message-None) 
Validates that the uploaded file is allowed by the given Flask-Uploads UploadSet. 
Parameters: 


e upload set— A list/tuple of extention names or an instance of 
flask.ext.uploads.UploadSet 


e message - error message 


You can also use the synonym file allowed. 


class flask wtf.file.FileRequired(message-None) 
Validates that field has a file. 
Parameters: message — error message 


You can also use the synonym file required. 
class flask wtf.html5.SearchlInput(input typezNone) 
Renders an input with type "search". 


class flask wtf.html5.SearchField(label-zNone, validators=None, filters=(), description-u'' 


Represents an <input type-"search'» . 


class flask wtf.html5.URLInput(input type-None) 


Renders an input with type "url". 


class flask wtf.html5.URLField(label-zNone, validators=None, filters=(), description=u'', i: 


Represents an «input type="url">. 


class flask wtf.html5.Emaillnput(input type-None) 


Renders an input with type "email". 


class flask wtf.html5.EmailField(label-zNone, validators=None, filters=(), description=u'', 


Represents an «input type="email"> . 


class flask wtf.html5.TellInput(input type-None) 


Renders an input with type "tel". 


class flask wtf.html5.TelField(label-None, validators=None, filters-(), description=u'', i: 


Represents an <input type="tel"> . 


class flask wtf.html5.NumberInput(step-zNone) 


Renders an input with type “number”. 


class flask wtf.html5.IntegerField(label-zNone, validators=None, **kwargs) 


Represents an «input type="number"> . 


class flask wtf.html5.DecimalField(label-None, validators=None, places-«unset value», roun 


Represents an «input type="number"> . 


class flask wtf.html5.RangelInput(stepzNone) 


Renders an input with type "range". 


class flask wtf.html5.IntegerRangeField(label-zNone, validators=None, **kwargs) 


Represents an «input type="range"> . 


class flask wtf.html5.DecimalRangeField(label-zNone, validators=None, places-«unset value», 


Represents an <input type="range"> . 


CSRF (RiP 


class flask wtf.csrf.CsrfProtect(appzNone) 
Enable csrf protect for Flask. 


Register it with: 


app = Flask( name ) 
CsrfProtect(app) 


And in the templates, add the token input: 


«input type="hidden" name-"csrf token" value="{{ csrf token() }}"/> 


If you need to send the token via AJAX, and there is no form: 


«meta name-z'"csrf token" content="{{ csrf token() }}" /> 


You can grab the csrf token with JavaScript, and send the token together. 


error handler(view) 
A decorator that set the error response handler. 


It accepts one parameter reason : 


Qcsrf.error handler 
def csrf error(reason): 
return render template('error.html', reason=reason) 


By default, it will return a 400 response. 


exempt ( view) 
A decorator that can exclude a view from csrf protection. 


Remember to put the decorator above the route : 


csrf = CsrfProtect(app) 


@csrf.exempt 
@app.route('/some-view', methods=['POST' ] ) 
def some_view(): 

return 


flask_wtf.csrf.generate_csrf(secret_key=None, time_limit=None) 
Generate csrf token code. 
Parameters: 


e secret key — A secret key for mixing in the token, default is Flask.secret key. 
e time limit — Token valid in the time limit, default is 3600s. 


flask wtf.csrf.validate csrf(data, secret key-zNone, time limit-None) 
Check if the given data is a valid csrf token. 
Parameters: 


e data — The csrf token value to be checked. 
e secret key — A secret key for mixing in the token, default is Flask.secret key. 
e time limit — Check if the csrf token is expired. default is True. 


升级 到 新 版 本 


Flask-WTF 像 其 它 软件 一 样 随时 间 推 移 而 改动 。 大 多 数 改 动 是 良性 的 ， 就 是 当 你 升级 到 新 版 
而 无 需 做 出 任何 改动 的 良性 。 


尽管 如 此 ， 每 隔 一 段 时 间 ， 就 会 有 需要 你 对 代码 做 出 改动 或 是 允许 你 改善 你 自己 的 代码 质量 
来 从 Flask-WTF 新 特性 获 益 的 改动 。 


本 节 文 档 列举 所 有 Flask-WTF 版 本 中 的 所 有 变更 以 及 如 何 进行 无 痛苦 的 升级 。 
如 果 你 想 用 pip 命令 升级 Flask-WTF， 确 保 传 递 -U SA: 


$ pip install -U Flask-WTF 


版 本 0.9.0 


ER wtforms 的 导入 是 一 个 重大 的 改变 ， 这 可 能 会 给 你 带 来 许多 痛苦 ， 但 这 些 导 和 人 项 难以 维 
护 。 你 需要 从 原始 的 WTForms 中 导入 Fields ， 而 不 是 从 Flask-WTF 中 导入 : 


from wtforms import TextField 


配置 选项 csRF ENABLED 改 为 wrF csRF ENABLED 。 如 果 你 没有 设置 任何 配置 选项 ， 那 么 你 无 
须 做 任何 变动 。 


这 个 版 本 有 很 多 的 特色 功能 ， 如 果 你 不 需要 他 们 ， 他 们 不 会 对 你 的 任何 代码 有 影响 。 


Flask-WTF 更 新 历史 


Flask-WTF 的 所 有 发 布 版 本 的 变更 列表 。 


Version 0.12 


Released 2015/07/09 


e Abstract protect csrf() into a separate method 
e Update reCAPTCHA configuration 
e Fix reCAPTCHA error handle 


Version 0.11 


Released 2015/01/21 


e Use the new reCAPTCHA API via #164. 


Version 0.10.3 


Released 2014/11/16 


e Add configuration: WTF_CSRF_HEADERS via #159. 
e Support customize hidden tags via #150. 
e And many more bug fixes 


Version 0.10.2 


Released 2014/09/03 


e Update translation for reCaptcha via #146. 


Version 0.10.1 


Released 2014/08/26 


e Update RECAPTCHA API SERVER URL via #145. 
e Update requirement Werkzeug? 70.9.5 
e Fix CsrfProtect exempt for blueprints via #143. 


Version 0.10.0 


Released 2014/07/16 


e Add configuration: WTF CSRF METHODS 
e Support WTForms 2.0 now 


Fix csrf validation without time limit (time limitzFalse) 


CSRF exempt supports blueprint #111. 


Version 0.9.5 


Released 2014/03/21 


e csrf token for all template types #112. 
e Make FileRequired a subclass of InputRequired #108. 


Version 0.9.4 


Released 2013/12/20 


e Bugfix for csrf module when form has a prefix 


e Compatible support for wtforms2 
e Remove file API for FileField 


Version 0.9.3 


Released 2013/10/02 


e Fix validation of recaptcha when app in testing mode #89. 
e Bugfix for csrf module #91 


Version 0.9.2 


Released 2013/9/11 


e Upgrade wtforms to 1.0.5. 

e No lazy string for i18n #77. 

No Datelnput widget in html5 #81. 
PUT and PATCH for CSRF #86. 


Version 0.9.1 


Released 2013/8/21 


This is a patch version for backward compitable for Flask«0.10 #82. 


Version 0.9.0 


Released 2013/8/15 


e Add i18n support (issue #65) 

e Use default html5 widgets and fields provided by wtforms 
e Python 3.3+ support 

e Redesign form, replace SessionSecureForm 

e CSRF protection solution 

e Drop wtforms imports 

e Fix recaptcha i18n support 

e Fix recaptcha validator for python 3 

e More test cases, it's 90%+ coverage now 

e Redesign documentation 


Version 0.8.4 


Released 2013/3/28 


e Recaptcha Validator now returns provided message (issue #66) 
e Minor doc fixes 
e Fixed issue with tests barking because of nose/multiprocessing issue. 


Version 0.8.3 


Released 2013/3/13 


e Update documentation to indicate pending deprecation of WTForms namespace facade 
e PEP8 fixes (issue #64) 
e Fix Recaptcha widget (issue #49) 


Version 0.8.2 and prior 


Initial development by Dan Jacob and Ron Duplain. 0.8.2 and prior there was not a change 
log. 


作者 


Flask-WTF 是 由 Dan Jacob 创建 ， 现 在 是 由 Hsiaoming Yang 维护 。 


贡献 者 


贡献 过 补丁 和 建议 的 人 们 : 


e Dan Jacob 

e Ron DuPlain 

e Daniel Lepage 
e Anthony Ford 

e Hsiaoming Yang 


更 多 的 贡献 者 可 以 在 GitHub 上 找到 。 


BSD 许 吕 证 


Copyright (c) 2010 by Dan Jacob. Copyright (c) 2013 - 2014 by Hsiaoming Yang. 
Some rights reserved. 


Redistribution and use in source and binary forms, with or without modification, are 
permitted provided that the following conditions are met: 


e Redistributions of source code must retain the above copyright notice, this list of 
conditions and the following disclaimer. 

e Redistributions in binary form must reproduce the above copyright notice, this list of 
conditions and the following disclaimer in the documentation and/or other materials 
provided with the distribution. 

e The names of the contributors may not be used to endorse or promote products derived 
from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 


